Merge pull request #38 from pyozig/dev

v0.11.4: Signature stub override, PyMemoryView_Check, branch quota fix

Author: dzonerzy

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to PyOZ will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.4] - 2026-02-19
+
+### Added
+- **`pyoz.Signature(T, "python_type")` -- stub return type override** - New comptime wrapper type that overrides the Python type annotation in generated `.pyi` stubs without affecting runtime behavior. Use this when the Zig return type doesn't map cleanly to the desired Python type, most commonly when `?T` is used for CPython exception signaling (returning `null` + `PyErr_SetString`) rather than representing Python `None`. For example, `fn probe() pyoz.Signature(?Dict, "dict[str, bool]")` generates `def probe() -> dict[str, bool]` instead of the incorrect `def probe() -> dict[str, bool] | None`. Also supports `pyoz.Signature(?void, "Never")` for functions that only raise. Works uniformly on module-level functions, class instance/static/class methods, `__call__`, `__new__`, and `allowThreads`/`allowThreadsTry`.
+- **`PyMemoryView_Check`** - Added type check function for `memoryview` objects, following the same `isTypeOrSubtype` pattern as other type checks. Uses `PyMemoryView_Type` which is part of the stable ABI since Python 3.2, so works across 3.8–3.13 in both normal and ABI3 modes.
+
+### Fixed
+- **Comptime branch quota exceeded with large modules** - Modules with many functions would fail to compile with `evaluation exceeded 1000 backwards branches` in `anyFuncUsesDateTime`/`anyFuncUsesDecimal`. Fixed by setting `@setEvalBranchQuota(std.math.maxInt(u32))` in both functions.
+
+### Refactored
+- **Type check functions** - `PySet_Check`, `PyFrozenSet_Check`, `PyBytes_Check`, `PyByteArray_Check`, and `PyObject_TypeCheck` now use the shared `isTypeOrSubtype` helper for consistency.
+
+### Removed
+- **`method__returns__` class method stub override** - The `pub const method_name__returns__: []const u8 = "..."` convention for overriding class method return type stubs has been removed in favor of the unified `pyoz.Signature(T, "python_type")` approach, which works identically for both module-level functions and class methods.
+
 ## [0.11.3] - 2026-02-10
 
 ### Fixed

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .PyOZ,
-    .version = "0.11.3",
+    .version = "0.11.4",
     .fingerprint = 0x4d3668413e69d99e,
     .dependencies = .{},
     .paths = .{

docs/guide/classes.md

@@ -654,23 +654,38 @@ class Node:
         ...
 ```
 
-### Return Type Override (`__returns__`)
+### Return Type Override (`Signature`)
 
-When a method returns `?*pyoz.PyObject`, the stub shows `Any | None`. Override it with the concrete Python type:
+When a method returns `?T` only to signal errors (not to return `None`), or returns `?*pyoz.PyObject` for a complex type, the inferred stub annotation won't match the actual Python API. Use `pyoz.Signature(T, "stub_string")` as the return type to override it:
 
 ```zig
 const Node = struct {
-    pub const children__returns__: []const u8 = "list[Node]";
+    pub fn children(self: *const Node) pyoz.Signature(?*pyoz.PyObject, "list[Node]") {
+        const list = buildChildList(self) orelse {
+            _ = pyoz.raiseRuntimeError("failed to build children");
+            return .{ .value = null };
+        };
+        return .{ .value = list };
+    }
 
-    pub fn children(self: *const Node) ?*pyoz.PyObject { ... }
+    pub fn find(self: *const Node, name: []const u8) pyoz.Signature(?Node, "Node") {
+        // null signals an error, not a None return
+        return .{ .value = self.doFind(name) orelse {
+            _ = pyoz.raiseKeyError("not found");
+            return .{ .value = null };
+        }};
+    }
 };
 ```
 
 Generated stub:
 ```python
 def children(self) -> list[Node]: ...
+def find(self, arg0: str) -> Node: ...
 ```
 
+`Signature` works the same way for instance methods, static methods, and class methods. See [Return Type Override](stubs.md#return-type-override-signature) for full details.
+
 ### Parameter Names (`__params__`)
 
 Zig's `@typeInfo` does not expose function parameter names, so stubs default to `arg0, arg1, ...`. Override with actual names:

docs/guide/functions.md

@@ -75,6 +75,7 @@ Struct fields with defaults become optional keyword arguments. Fields without de
 | `struct { T, U }` | `tuple` |
 | `[]const T` | `list` |
 | `pyoz.Owned(T)` | Same as `T` (frees backing memory) |
+| `pyoz.Signature(T, "S")` | Stub shows `S` instead of inferred type |
 
 ## Error Handling
 
@@ -117,6 +118,19 @@ fn heavy_compute(n: i64) i64 {
 
 See [GIL Management](gil.md) for details.
 
+## Stub Return Type Override
+
+When a function returns `?T` only to signal errors (not to return `None` to Python), the generated stub shows `T | None` — which is misleading. Use `pyoz.Signature(T, "stub_string")` to override the stub annotation:
+
+```zig
+fn validate(n: i64) pyoz.Signature(?i64, "int") {
+    if (n < 0) return pyoz.raiseValueError("must be non-negative");
+    return .{ .value = n };
+}
+```
+
+The stub shows `-> int` instead of `-> int | None`. At runtime, `Signature` is transparent — PyOZ unwraps the `.value` field automatically. See [Type Stubs: Return Type Override](stubs.md#return-type-override-signature) for more details.
+
 ## Docstrings
 
 The third argument to function registrations becomes the Python docstring:

docs/guide/stubs.md

@@ -33,6 +33,7 @@ PyOZ generates stubs for all exported items:
 | `[]const u8` | `str` |
 | `void` | `None` |
 | `?T` | `T \| None` |
+| `pyoz.Signature(?T, "U")` | `U` (user-defined override) |
 | `!T` | `T` |
 | `pyoz.Complex` | `complex` |
 | `pyoz.Date` | `datetime.date` |
@@ -110,6 +111,63 @@ mypy my_script.py
 pyright my_script.py
 ```
 
+## Return Type Override (`Signature`)
+
+Sometimes the automatically inferred stub type doesn't match the intended Python-level API. The most common case: a function returns `?T` (optional) only to signal errors via `null`, but the Python caller never sees `None` — they see a raised exception instead. The stub would show `T | None` when it should just show `T`.
+
+Use `pyoz.Signature(T, "stub_string")` as the return type to override the stub annotation while preserving runtime behavior:
+
+```zig
+fn validate_positive(n: i64) pyoz.Signature(?i64, "int") {
+    if (n < 0) {
+        _ = pyoz.raiseValueError("must be non-negative");
+        return .{ .value = null };
+    }
+    return .{ .value = n };
+}
+```
+
+Generated stub:
+```python
+def validate_positive(arg0: int) -> int: ...
+```
+
+Without `Signature`, the stub would show `-> int | None`.
+
+### How It Works
+
+`Signature` is a comptime wrapper type. At runtime it's a struct with a single `.value` field — PyOZ unwraps it automatically, so Python never sees the wrapper. The second parameter (the string) is used verbatim as the return type annotation in the generated `.pyi` file.
+
+### Works Everywhere
+
+`Signature` works identically for module-level functions and class methods (instance, static, and class methods):
+
+```zig
+const Parser = struct {
+    pub fn parse(self: *const Parser, input: []const u8) pyoz.Signature(?Node, "Node") {
+        // null signals an error, not a None return
+        if (input.len == 0) {
+            _ = pyoz.raiseValueError("empty input");
+            return .{ .value = null };
+        }
+        return .{ .value = self.doParse(input) };
+    }
+};
+```
+
+Generated stub:
+```python
+def parse(self, arg0: str) -> Node: ...
+```
+
+### When to Use
+
+| Scenario | Without Signature | With Signature |
+|----------|-------------------|----------------|
+| `?T` where `null` = error | `T \| None` | Use `Signature(?T, "T")` |
+| Raw `*PyObject` return | `Any` | Use `Signature(*PyObject, "list[Node]")` |
+| Complex generic return | `Any` | Use `Signature(*PyObject, "dict[str, list[int]]")` |
+
 ## Limitations
 
 - Generic types may show as `Any` for complex cases

docs/reference/api.md

@@ -276,6 +276,27 @@ return pyoz.owned(allocator, data);  // returns Owned([]const u8)
 
 Supports `!Owned(T)` (error union) and `?Owned(T)` (optional) return types.
 
+## Stub Return Type Override
+
+### `pyoz.Signature(T, "stub_string")`
+
+Override the `.pyi` stub return type annotation while preserving runtime behavior. `T` is the actual Zig return type; `"stub_string"` is written verbatim into the generated stub.
+
+```zig
+fn validate(n: i64) pyoz.Signature(?i64, "int") {
+    if (n < 0) return pyoz.raiseValueError("must be non-negative");
+    return .{ .value = n };
+}
+```
+
+At runtime, `Signature` is a struct with a `.value` field — PyOZ unwraps it automatically. Works for module-level functions and class methods (instance, static, class).
+
+| Usage | Stub Output |
+|-------|-------------|
+| `pyoz.Signature(?i64, "int")` | `-> int` |
+| `pyoz.Signature(?*PyObject, "list[Node]")` | `-> list[Node]` |
+| `pyoz.Signature(?Node, "Node")` | `-> Node` |
+
 ## Strong References
 
 ### `pyoz.Ref(T)`

examples/example_module.zig

@@ -44,6 +44,15 @@ fn validate_positive(n: i64) ?i64 {
     return n;
 }
 
+/// Validate positive with Signature override - stubs should show `int` not `int | None`
+fn validate_positive_sig(n: i64) pyoz.Signature(?i64, "int") {
+    if (n < 0) {
+        Example.getException(0).raise("Value must be non-negative");
+        return .{ .value = null };
+    }
+    return .{ .value = n };
+}
+
 /// Safe divide using custom exception
 fn safe_divide(a: f64, b: f64) ?f64 {
     if (b == 0.0) {
@@ -2957,6 +2966,7 @@ const Example = pyoz.module(.{
         pyoz.func("multiply", multiply, "Multiply two floats"),
         pyoz.func("divide", divide, "Divide two numbers (raises error if b=0)"),
         pyoz.func("validate_positive", validate_positive, "Validate that a number is non-negative"),
+        pyoz.func("validate_positive_sig", validate_positive_sig, "Validate positive (Signature override)"),
         pyoz.func("safe_divide", safe_divide, "Divide with custom exception on zero"),
         pyoz.kwfunc("greet_person", greet_person, "Greet a person with optional greeting and times"),
         pyoz.kwfunc("power", power, "Calculate base^exponent (default exponent=2)"),

pypi/build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .pyoz,
-    .version = "0.11.3",
+    .version = "0.11.4",
     .fingerprint = 0x43eec3150282fd1f,
     .dependencies = .{
         .PyOZ = .{

pypi/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyoz"
-version = "0.11.3"
+version = "0.11.4"
 description = "Python extension modules in Zig, made easy"
 readme = "README.md"
 license = "MIT"

pypi/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = pyoz
-version = 0.11.3
+version = 0.11.4
 
 [options]
 packages = pyoz