Metadata-Version: 2.4
Name: fry-return
Version: 0.1.0
Summary: A structured return object for Python functions — carries status code, message, data, and details.
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/fanrenyi33/fry_python_lib_d100_fry_return
Project-URL: Repository, https://gitlab.com/fanrenyi33/fry_python_lib_d100_fry_return
Keywords: return,result,response,status
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# fry-return

A structured return object for Python functions. Instead of returning bare dicts or raising exceptions for every non-happy path, wrap your result in a `FryReturnObj` — it carries a typed status code, a human-readable message, optional data payload, and a list of detail strings.

## Installation

```bash
pip install fry-return
```

## Quick start

```python
from fry_return import FryReturnObj, FryReturnCode
```

### Direct usage — data goes into `data_dict`

Simple but less IDE-friendly: you get no autocomplete on the payload fields.

```python
def get_user(user_id: int) -> FryReturnObj:
    user = db.find(user_id)
    if user is None:
        return FryReturnObj.failed("用户不存在")
    return FryReturnObj.success("查询成功").set_data("user", user)

result = get_user(42)
if result.is_success:
    print(result.data_dict["user"])
else:
    print(result.message_str)
```

### Inheritance — core data as typed attributes (recommended)

Define a subclass and add your payload as proper typed fields. Editors will autocomplete everything.

```python
from dataclasses import dataclass, field
from fry_return import FryReturnObj, FryReturnCode

@dataclass
class GetUserResult(FryReturnObj):
    user_id: int = 0
    username: str = ""
    email: str = ""

def get_user(user_id: int) -> GetUserResult:
    user = db.find(user_id)
    if user is None:
        return GetUserResult(code=FryReturnCode.FAILED, message_str="用户不存在")

    result = GetUserResult(code=FryReturnCode.SUCCESS, message_str="查询成功")
    result.user_id = user.id
    result.username = user.name
    result.email = user.email
    return result

result = get_user(42)
if result.is_success:
    print(result.username)   # 编辑器可以自动补全
    print(result.email)
```

### Chaining

```python
result = (
    FryReturnObj.info("开始处理")
    .add_detail("步骤1完成")
    .add_detail("步骤2完成")
    .set_success("全部完成")
    .set_data("count", 10)
)
```

### Serialization

```python
d = result.to_dict()          # -> dict，可直接 JSON 序列化
r = FryReturnObj.from_dict(d) # 从 dict 还原
```

## Status codes (`FryReturnCode`)

| 名称 | 值 | 说明 |
|---|---|---|
| `DEBUG` | 100 | 调试信息 |
| `INFO` | 200 | 普通信息 |
| `IMPORTANT` | 300 | 重要信息 |
| `WARNING` | 400 | 警告 |
| `VALIDATE` | 500 | 验证失败 |
| `FAILED` | 600 | 操作失败 |
| `BUG` | 700 | 程序错误 |
| `SUCCESS` | 800 | 完全成功 |
| `PARTIAL_SUCCESS` | 820 | 部分成功 |

## Key properties

| 属性 | 说明 |
|---|---|
| `is_success` / `is_full_success` | 是否为 SUCCESS |
| `is_partial_success` | 是否为 PARTIAL_SUCCESS |
| `code_name` | 状态码名称字符串 |
| `code_value` | 状态码数值 |

## License

MIT
