Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Dev2Forge/BasicReturns/llms.txt

Use this file to discover all available pages before exploring further.

BasicReturn is the foundation of the BasicReturns library. It is a Pydantic v2 BaseModel subclass that represents the outcome of any operation — success or failure — in a consistent, type-safe structure. Every function that uses BasicReturns returns at minimum an instance of BasicReturn, giving callers a predictable interface regardless of what the function does internally.

​
Import

from BasicReturns import BasicReturn

​
Class Definition

from typing import Any, Optional
from pydantic import BaseModel

class BasicReturn(BaseModel):
    """Have a basic return model, contains `ok` and `error` properties."""
    ok: Optional[bool] = True
    error: Optional[Any] = None

    def __str__(self) -> str:
        return f'OK: {self.ok}\nError: {self.error}'

    def to_dict(self) -> dict:
        """Get a self representation as dictionary"""
        return {"ok": self.ok, "error": self.error}

​
Fields

​
ok
Optional[bool]
default:"True"
True when the operation succeeded; set to False on failure. Mirrors the semantics of an HTTP success response — a truthy value signals the caller that the operation completed without error.
​
error
Optional[Any]
default:"None"
Holds the exception or error object when ok is False. Remains None on success. Accepts any Python value — an Exception subclass, a string message, or any custom error object.

​
Methods

​
to_dict()

Returns a plain Python dictionary representation of the instance. This is useful at serialization boundaries — for example, before passing the return value to json.dumps() or a web framework response helper. Return type: dict 
response = BasicReturn()
print(response.to_dict())  # {'ok': True, 'error': None}

failed = BasicReturn(ok=False, error=ValueError("something went wrong"))
print(failed.to_dict())  # {'ok': False, 'error': ValueError('something went wrong')}

​
__str__()

Returns a human-readable, multi-line string representation of the instance. Handy for logging and debugging. Return type: str
Format: OK: {ok}\nError: {error} 
response = BasicReturn(ok=False, error=FileNotFoundError("config.yaml not found"))
print(str(response))
# OK: False
# Error: [Errno 2] No such file or directory: 'config.yaml not found'

​
Usage Example

The canonical pattern is to wrap the body of a function in a try/except block and return a BasicReturn in both branches. Callers can then check result.ok before proceeding. 
from BasicReturns import BasicReturn

def save_config(path: str, content: str) -> BasicReturn:
    """Write content to a file and return a BasicReturn indicating success or failure."""
    try:
        with open(path, "w", encoding="utf-8") as f:
            f.write(content)
        return BasicReturn()  # ok=True, error=None by default
    except Exception as e:
        return BasicReturn(ok=False, error=e)


# --- Caller ---
result = save_config("/etc/myapp/config.yaml", "debug: true")

if result.ok:
    print("Config saved successfully.")
else:
    print(f"Failed to save config: {result.error}")

​
When to Use BasicReturn vs DataAndMsgReturn

ScenarioRecommended class
Write, delete, send, or any fire-and-forget operationBasicReturn
Operation that returns a result payload or a messageDataAndMsgReturn
Lightweight success/failure signal with no extra contextBasicReturn
API handler that needs structured JSON with msg and dataDataAndMsgReturn
Use BasicReturn when the operation’s only meaningful outcome is whether it succeeded or failed — there is no data to return to the caller. If you find yourself stuffing results into the error field on success, that is a clear signal to switch to DataAndMsgReturn instead.
BasicReturn extends Pydantic’s BaseModel, so you can construct it with keyword arguments just like any other Pydantic model:
BasicReturn(ok=False, error=ValueError("oops"))
Pydantic will validate the field types at construction time, making it safe to use in strictly-typed codebases.
Need to return data or a human-readable message alongside ok and error? See the DataAndMsgReturn reference — it extends BasicReturn with msg and data fields without changing any existing behaviour.

Build docs developers (and LLMs) love

Get started for freeTalk to us