with-err 1.0.0__tar.gz

with_err-1.0.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: with-err
+Version: 1.0.0
+Summary: converting `try-except` pattern to Go-like `result, err` pattern.
+Keywords: 
+Author: Chuan-Heng Hsiao
+Author-email: Chuan-Heng Hsiao <hsiao.chuanheng@gmail.com>
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/chhsiao1981/with-err
+Description-Content-Type: text/markdown
+
+# with-err
+
+`with-err` is a python library that converts `try-except` pattern into Go-like `result, err` pattern. I feel `result, err` pattern easier to maintain in large projects.
+
+## Getting Started
+
+### Install
+
+```sh
+pip install with-err
+```
+
+(with [`uv`](https://docs.astral.sh/uv/))
+```sh
+uv pip install with-err
+```
+
+### Use as Function
+
+```python
+import json
+from with_err import with_err
+
+json_loads_e = with_err()(json.loads)
+
+data, err = json_loads_e('{"a": 1}')
+assert err is None
+assert data = {"a": 1}
+
+data, err = json_loads_e('{"a": }')
+assert err is not None
+assert data is None
+```
+
+### Use as Decorator
+
+```python
+import json
+from with_err import with_err
+
+@with_err()
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+data, err = json_loads_e('{"a": 1}')
+assert err is None
+assert data = {"a": 1}
+
+data, err = json_loads_e('{"a": }')
+assert err is not None
+assert data is None
+```
+
+### `with_err` with Specified Exceptions
+
+```python
+import json
+from with_err import with_err
+
+@with_err(json.decoder.JSONDecodeError)
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+data, err = json_loads_e('{"a": 1}')
+assert err is None
+assert data = {"a": 1}
+
+data, err = json_loads_e('{"a": }')
+assert err is not None
+assert data is None
+```
+
+### Get `err` Traceback Stack
+
+```python
+import json
+from with_err import with_err, get_err_strs
+
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+_data, err = json_loads_e('{"a": 1}')
+err_stack = get_err_strs(err)
+assert err is None
+assert err_stack == []
+```
+
+```python
+import json
+import re
+from with_err import with_err, get_err_strs
+
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+_data, err = json_loads_e('{"a": }')
+err_stack = get_err_strs(err)
+err_str = '\n'.join(err_stack)
+assert err is not None
+assert len(err_stack) > 0
+assert re.search(r'json/__init__.py", line \d+, in loads', err_str)
+assert re.search(r', line \d+, in json_loads_e', err_str)
+```

with_err-1.0.0/README.md

@@ -0,0 +1,103 @@
+# with-err
+
+`with-err` is a python library that converts `try-except` pattern into Go-like `result, err` pattern. I feel `result, err` pattern easier to maintain in large projects.
+
+## Getting Started
+
+### Install
+
+```sh
+pip install with-err
+```
+
+(with [`uv`](https://docs.astral.sh/uv/))
+```sh
+uv pip install with-err
+```
+
+### Use as Function
+
+```python
+import json
+from with_err import with_err
+
+json_loads_e = with_err()(json.loads)
+
+data, err = json_loads_e('{"a": 1}')
+assert err is None
+assert data = {"a": 1}
+
+data, err = json_loads_e('{"a": }')
+assert err is not None
+assert data is None
+```
+
+### Use as Decorator
+
+```python
+import json
+from with_err import with_err
+
+@with_err()
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+data, err = json_loads_e('{"a": 1}')
+assert err is None
+assert data = {"a": 1}
+
+data, err = json_loads_e('{"a": }')
+assert err is not None
+assert data is None
+```
+
+### `with_err` with Specified Exceptions
+
+```python
+import json
+from with_err import with_err
+
+@with_err(json.decoder.JSONDecodeError)
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+data, err = json_loads_e('{"a": 1}')
+assert err is None
+assert data = {"a": 1}
+
+data, err = json_loads_e('{"a": }')
+assert err is not None
+assert data is None
+```
+
+### Get `err` Traceback Stack
+
+```python
+import json
+from with_err import with_err, get_err_strs
+
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+_data, err = json_loads_e('{"a": 1}')
+err_stack = get_err_strs(err)
+assert err is None
+assert err_stack == []
+```
+
+```python
+import json
+import re
+from with_err import with_err, get_err_strs
+
+def json_loads_e(a: str | bytes | bytearray):
+    return json.loads(a)
+
+_data, err = json_loads_e('{"a": }')
+err_stack = get_err_strs(err)
+err_str = '\n'.join(err_stack)
+assert err is not None
+assert len(err_stack) > 0
+assert re.search(r'json/__init__.py", line \d+, in loads', err_str)
+assert re.search(r', line \d+, in json_loads_e', err_str)
+```

with_err-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "with-err"
+version = "1.0.0"
+description = "converting `try-except` pattern to Go-like `result, err` pattern."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = []
+keywords = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[[project.authors]]
+name = "Chuan-Heng Hsiao"
+email = "hsiao.chuanheng@gmail.com"
+
+[project.urls]
+Repository = "https://github.com/chhsiao1981/with-err"
+
+[project.scripts]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff==0.16.3",
+    "pytest==9.1.1",
+    "pytest-cov==7.1.0",
+    "lefthook==2.1.10",
+    "autopep8==2.3.2",
+]
+
+[tool.autopep8]
+max_line_length = 100
+
+[tool.ruff]
+line-length = 100
+preview = true
+
+[tool.ruff.lint]
+extend-select = [
+    "E",
+    "W",
+]

with_err-1.0.0/pyproject.toml.orig

@@ -0,0 +1,55 @@
+[project]
+name = 'with-err'
+version = '1.0.0'
+description = 'converting `try-except` pattern to Go-like `result, err` pattern.'
+readme = 'README.md'
+license = 'MIT'
+authors = [
+    {name = 'Chuan-Heng Hsiao', email = 'hsiao.chuanheng@gmail.com'},
+]
+requires-python = '>=3.12'
+dependencies = [
+]
+keywords = [
+]
+classifiers = [
+    'Programming Language :: Python :: 3',
+    'Operating System :: OS Independent',
+]
+
+[project.urls]
+# Homepage      = ''
+# Documentation = ''
+Repository = 'https://github.com/chhsiao1981/with-err'
+# 'Bug Tracker' = ''
+# Changelog = ''
+
+[project.scripts]
+
+[build-system]
+requires = [
+    'uv_build>=0.12.5,<0.13.0',
+]
+build-backend = 'uv_build'
+
+[dependency-groups]
+dev = [
+    'ruff==0.16.3',      # use ruff check --fix, not ruff format.
+    'pytest==9.1.1',
+    'pytest-cov==7.1.0',
+    'lefthook==2.1.10',
+    'autopep8==2.3.2',   # autopep8 is better in whitespace formatting.
+]
+
+[tool.autopep8]
+max_line_length = 100
+
+[tool.ruff]
+line-length = 100
+preview     = true
+
+[tool.ruff.lint]
+extend-select = [
+    'E',
+    'W',
+]

with_err-1.0.0/src/with_err/__init__.py

@@ -0,0 +1,7 @@
+from .utils import get_err_strs as get_err_strs
+from .with_err import with_err as with_err
+
+all = [
+    'with_err',
+    'get_err_strs'
+]

with_err-1.0.0/src/with_err/utils.py

@@ -0,0 +1,11 @@
+# https://share.gemini.google/BDvazjX2RWsE
+
+import traceback
+
+
+def get_err_strs(err: Exception | None) -> list[str]:
+    """Accepts an exception instance and returns the full traceback as list[str]."""
+    if err is None:
+        return []
+
+    return traceback.format_exception(err)

with_err-1.0.0/src/with_err/with_err.py

@@ -0,0 +1,65 @@
+# https://share.gemini.google/BDvazjX2RWsE
+
+import sys
+import types
+from collections.abc import Callable
+from functools import wraps
+from typing import Protocol
+
+
+# @type_check_only
+class RetWithErr[**P, R](Protocol):
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> tuple[R | None, Exception | None]:
+        ...
+
+
+def with_err[**P, R](*exceptions: type[Exception]) -> Callable[[Callable[P, R]], RetWithErr[P, R]]:
+    """
+    Wraps a function to return (result, Exception) instead of raising.
+
+    XXX Reason repeating exceptions and Exception:
+        We don't want to create another layer of function tracestack.
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, tuple[R | None, Exception | None]]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> tuple[R | None, Exception | None]:
+            try:
+                result = func(*args, **kwargs)
+                return result, None
+            except exceptions as e:
+                # 1. Fetch exception's original internal traceback.
+                tb = sys.exc_info()[2]
+
+                # 2. Capture the caller frame executing func.
+                caller_frame = sys._getframe(1)
+
+                # 3. Create a parent traceback frame and link it above 'tb'.
+                combined_tb = types.TracebackType(
+                    tb_next=tb,
+                    tb_frame=caller_frame,
+                    tb_lasti=caller_frame.f_lasti,
+                    tb_lineno=caller_frame.f_lineno
+                )
+
+                # 4. Attach the combined traceback back to the error instance
+                return None, e.with_traceback(combined_tb)
+            except Exception as e:  # ruff: ignore[blind-except]
+                # 1. Fetch exception's original internal traceback.
+                tb = sys.exc_info()[2]
+
+                # 2. Capture the caller frame executing func.
+                caller_frame = sys._getframe(1)
+
+                # 3. Create a parent traceback frame and link it above 'tb'.
+                combined_tb = types.TracebackType(
+                    tb_next=tb,
+                    tb_frame=caller_frame,
+                    tb_lasti=caller_frame.f_lasti,
+                    tb_lineno=caller_frame.f_lineno
+                )
+
+                # 4. Attach the combined traceback back to the error instance
+                return None, e.with_traceback(combined_tb)
+        return wrapper
+    return decorator