fabric-chaincode-python 2.5.2__py3-none-any.whl

src/fabric_contract_api/internal/transaction_handler.py

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Transaction handler for before/after/unknown transactions.
+
+This is the Python equivalent of Go's ``internal/transaction_handler.go``.
+A :class:`TransactionHandler` is a thin specialisation of
+:class:`ContractFunction` for the three "lifecycle" hooks every contract can
+define:
+
+* ``BeforeTransaction`` — called before the named function.
+* ``AfterTransaction`` — called after the named function (and receives its
+  return value).
+* ``UnknownTransaction`` — called when an unknown function name is requested.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Optional, Tuple
+
+from .contract_function import ContractFunction
+
+
+class TransactionHandlerType:
+    """Enum-like constants for the three handler types."""
+
+    BEFORE = 1
+    UNKNOWN = 2
+    AFTER = 3
+
+    @staticmethod
+    def to_string(value: int) -> str:
+        if value == TransactionHandlerType.BEFORE:
+            return "Before"
+        if value == TransactionHandlerType.AFTER:
+            return "After"
+        if value == TransactionHandlerType.UNKNOWN:
+            return "Unknown"
+        raise ValueError("invalid transaction handler type")
+
+
+class TransactionHandler(ContractFunction):
+    """Specialised :class:`ContractFunction` for before/after/unknown hooks."""
+
+    def __init__(self, fn: Callable[..., Any], context_handler_type: Any,
+                 handles_type: int) -> None:
+        super().__init__(
+            fn=fn,
+            call_type=0,
+            param_details=_empty_params(),
+            return_details=_empty_returns(),
+        )
+        # Re-parse to populate params/returns correctly.
+        param_details, return_details = self._parse(fn, context_handler_type)
+        self.params = param_details
+        self.returns = return_details
+        self.handles_type = handles_type
+
+    async def call(self, ctx: Any, data: Any, serializer) -> Tuple[str, Any, Optional[Exception]]:  # type: ignore[override]
+        """Invoke the hook.
+
+        For ``TransactionHandlerTypeAfter`` *data* is the success value (or
+        ``None``) returned by the named transaction function.
+        """
+        values = []
+        if self.params.context is not None:
+            values.append(ctx)
+
+        # Only after-transactions may take the success value as an additional
+        # parameter.
+        if self.handles_type == TransactionHandlerType.AFTER and len(self.params.fields) == 1:
+            if data is None:
+                # Mirror Go's behaviour: when the named function returned no
+                # success value, pass an "undefined" sentinel.
+                from ..contractapi.utils.undefined_interface import UndefinedInterface
+                values.append(UndefinedInterface())
+            else:
+                values.append(data)
+
+        try:
+            if inspect.iscoroutinefunction(self.function):
+                some_resp = await self.function(*values)
+            else:
+                some_resp = self.function(*values)
+        except Exception as exc:
+            return "", None, exc
+
+        return self._handle_response(some_resp, None, None, serializer)
+
+
+def _empty_params():
+    from .contract_function import _ContractFunctionParams
+    return _ContractFunctionParams()
+
+
+def _empty_returns():
+    from .contract_function import _ContractFunctionReturns
+    return _ContractFunctionReturns()
+
+
+def new_transaction_handler(fn: Callable[..., Any], context_handler_type: Any,
+                              handles_type: int) -> TransactionHandler:
+    """Create a new :class:`TransactionHandler`.
+
+    Mirrors Go's ``NewTransactionHandler``.  Raises ``ValueError`` if the
+    function does not satisfy the constraints of the requested handler type.
+    """
+    try:
+        th = TransactionHandler(fn, context_handler_type, handles_type)
+    except ValueError as exc:
+        htype_str = TransactionHandlerType.to_string(handles_type)
+        raise ValueError(f"error creating {htype_str}. {exc}") from exc
+
+    if handles_type != TransactionHandlerType.AFTER and len(th.params.fields) > 0:
+        htype_str = TransactionHandlerType.to_string(handles_type)
+        raise ValueError(
+            f"{htype_str} transactions may not take any params other than the transaction context"
+        )
+    if handles_type == TransactionHandlerType.AFTER and len(th.params.fields) > 1:
+        raise ValueError("after transactions must take at most one non-context param")
+    # In Python, "interface" matches any type, so we keep the Go constraint
+    # simple: the after-transaction may take at most one extra parameter,
+    # of any type.
+
+    return th
+
+
+__all__ = [
+    "TransactionHandler",
+    "TransactionHandlerType",
+    "new_transaction_handler",
+]

src/fabric_contract_api/internal/types.py

@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Basic type converters used by the JSON transaction serializer.
+
+This module is the Python equivalent of Go's
+``fabric-contract-api-go/internal/types`` package.  Each basic Python type
+has a small adapter that knows how to:
+
+1. Convert a ``str`` parameter coming from the Fabric transaction payload
+   into the underlying Python type (``int``, ``float``, ``bool``, ...).
+2. Produce a JSON-schema snippet (OpenAPI-style) describing the type so that
+   it can be embedded into the chaincode metadata.
+
+The Go implementation ships separate converters for ``int8``/``int16``/
+``int32``/``int64``/``uint8``/.../``uint64``/``float32``/``float64``.  In
+Python the only relevant numeric types are :class:`int` and :class:`float`,
+so we collapse the integer family onto ``int`` (unbounded) and the float
+family onto ``float`` (IEEE-754 double precision).
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Any, Callable, Dict, Optional, Tuple, Type
+
+# ``inspect`` annotations store classes (and ``typing`` aliases).  We use
+# ``type`` as a plain alias throughout this module for readability.
+TypeT = Type[Any]
+
+
+class _BasicType:
+    """Adapter for a single basic Python type.
+
+    Subclasses set :attr:`python_type` and override :meth:`convert` and
+    :meth:`get_schema`.
+    """
+
+    python_type: TypeT = object
+
+    def convert(self, value: str) -> Any:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+    def get_schema(self) -> Dict[str, Any]:
+        raise NotImplementedError
+
+
+class _StringType(_BasicType):
+    python_type = str
+
+    def convert(self, value: str) -> str:
+        return value
+
+    def get_schema(self) -> Dict[str, Any]:
+        return {"type": "string"}
+
+
+class _BoolType(_BasicType):
+    python_type = bool
+
+    def convert(self, value: str) -> bool:
+        if value == "":
+            return False
+        # Python's bool() would return True for any non-empty string, but we
+        # want strict parsing here so that "false" really means False.
+        lowered = value.strip().lower()
+        if lowered in ("true", "t", "1", "yes", "y"):
+            return True
+        if lowered in ("false", "f", "0", "no", "n"):
+            return False
+        raise ValueError(f"cannot convert passed value {value!r} to bool")
+
+    def get_schema(self) -> Dict[str, Any]:
+        return {"type": "boolean"}
+
+
+class _IntType(_BasicType):
+    python_type = int
+
+    def convert(self, value: str) -> int:
+        if value == "":
+            return 0
+        try:
+            return int(value, 10)
+        except ValueError as exc:
+            raise ValueError(
+                f"cannot convert passed value {value!r} to int"
+            ) from exc
+
+    def get_schema(self) -> Dict[str, Any]:
+        # JSON-schema "integer" with 64-bit range, matching the Go
+        # implementation's int64 property.
+        return {"type": "integer", "format": "int64"}
+
+
+class _FloatType(_BasicType):
+    python_type = float
+
+    def convert(self, value: str) -> float:
+        if value == "":
+            return 0.0
+        try:
+            return float(value)
+        except ValueError as exc:
+            raise ValueError(
+                f"cannot convert passed value {value!r} to float"
+            ) from exc
+
+    def get_schema(self) -> Dict[str, Any]:
+        return {"type": "number", "format": "float"}
+
+
+class _BytesType(_BasicType):
+    """Bytes/bytearray — handled as base64-free raw strings.
+
+    Fabric sends bytes as raw UTF-8 strings; we mirror that behaviour here.
+    The Go implementation uses ``[]byte(param)`` which is a byte-for-byte
+    cast of the UTF-8 bytes.
+    """
+
+    python_type = bytes
+
+    def convert(self, value: str) -> bytes:
+        return value.encode("utf-8")
+
+    def get_schema(self) -> Dict[str, Any]:
+        return {"type": "string", "format": "byte"}
+
+
+class _InterfaceType(_BasicType):
+    """``typing.Any`` / untyped parameter — accept the raw string."""
+
+    python_type = object
+
+    def convert(self, value: str) -> str:
+        return value
+
+    def get_schema(self) -> Dict[str, Any]:
+        return {}
+
+
+# Order matters: when several Python types share the same identity (e.g. bool
+# is a subclass of int), we need to check the more specific one first.
+BasicTypes: Dict[TypeT, _BasicType] = {
+    str: _StringType(),
+    bool: _BoolType(),
+    int: _IntType(),
+    float: _FloatType(),
+    bytes: _BytesType(),
+    bytearray: _BytesType(),
+    object: _InterfaceType(),
+}
+
+# Sentinel values mirroring Go's ``types.ErrorType`` and ``types.TimeType``.
+ErrorType: TypeT = type("ErrorType", (), {"__doc__": "Sentinel for the Go-style error return type"})
+TimeType: TypeT = _dt.datetime
+
+
+def is_bytes(t: TypeT) -> bool:
+    """Return ``True`` if *t* is a bytes/bytearray type.
+
+    Mirrors ``types.IsBytes`` from the Go implementation.
+    """
+    return t in (bytes, bytearray)
+
+
+def basic_type_for(t: TypeT) -> Optional[_BasicType]:
+    """Return the basic-type adapter for *t*, or ``None``.
+
+    Handles the ``bool`` is-a-subclass-of-``int`` gotcha by checking bool
+    before int.
+    """
+    return BasicTypes.get(t)
+
+
+__all__ = [
+    "BasicTypes",
+    "ErrorType",
+    "TimeType",
+    "is_bytes",
+    "basic_type_for",
+]

src/fabric_contract_api/internal/types_handler.py

@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Static type validation for contract functions.
+
+This module is the Python equivalent of Go's
+``fabric-contract-api-go/internal/types_handler``.  The goal is to walk
+through every parameter and return annotation of a contract's transaction
+function and verify that each one is a type the contract API can serialise.
+
+Allowed parameter types are:
+
+* the basic scalar types (``str``, ``bool``, ``int``, ``float``)
+* ``bytes`` / ``bytearray`` (treated as raw byte strings)
+* ``list[T]`` / ``typing.List[T]`` where ``T`` is itself an allowed type
+* ``dict[str, V]`` / ``typing.Dict[str, V]`` where ``V`` is allowed
+* arbitrary dataclasses or plain classes (treated as structured objects and
+  serialised as JSON)
+* ``typing.Any`` / ``object`` — accepted as opaque strings
+* :class:`datetime.datetime` — accepted as an RFC3339-formatted timestamp
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as _dt
+import typing as _t
+from typing import Any, List, Optional, Sequence, Tuple, Type
+
+from . import types as _types
+from .utils import slice_as_comma_sentence
+
+
+def _basic_types_as_slice() -> List[str]:
+    """Return a sorted list of the basic-type names."""
+    return sorted(t.__name__ for t in _types.BasicTypes)
+
+
+def list_basic_types() -> str:
+    """Return a comma-and-and sentence of the supported basic types."""
+    return slice_as_comma_sentence(_basic_types_as_slice())
+
+
+def _origin_is(tp: Any, origin: Any) -> bool:
+    """True if *tp*'s typing origin is *origin*.
+
+    Examples:
+        ``_origin_is(list[int], list)`` -> True
+        ``_origin_is(dict[str, int], dict)`` -> True
+    """
+    return _t.get_origin(tp) is origin
+
+
+def _type_kind(tp: Any) -> str:
+    """Return a human-friendly kind name for *tp*."""
+    if _t.get_origin(tp) is not None:
+        return str(_t.get_origin(tp))
+    if isinstance(tp, type):
+        return tp.__name__
+    return str(tp)
+
+
+def _strip_optional(tp: Any) -> Any:
+    """Strip a ``typing.Optional[X]`` / ``typing.Union[X, None]`` wrapper.
+
+    The contract API treats ``Optional[X]`` the same as ``X`` for the purposes
+    of validation (a missing argument coming through as ``""`` is still
+    converted to the zero-value of ``X``).
+    """
+    origin = _t.get_origin(tp)
+    if origin is _t.Union:
+        args = [a for a in _t.get_args(tp) if a is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return tp
+
+
+def type_is_valid(tp: Any, additional_types: Optional[Sequence[Any]] = None,
+                  allow_error: bool = False) -> Optional[str]:
+    """Validate that *tp* is a type the contract API can serialise.
+
+    Returns ``None`` when the type is valid, or an error message otherwise.
+
+    Args:
+        tp: The type to validate (a ``type`` instance, a ``typing`` alias,
+            or :data:`typing.Any`).
+        additional_types: A list of types that should additionally be allowed
+            (used for cyclic struct references).
+        allow_error: When ``True`` the sentinel :data:`types.ErrorType` is
+            also accepted as a valid type — this is used when validating
+            *return* types of contract functions.
+    """
+    additional_types = list(additional_types or [])
+
+    # Unwrap Optional[X] -> X
+    tp = _strip_optional(tp)
+
+    if tp is _t.Any or tp is object:
+        return None
+
+    # typing.List / typing.Dict / typing.Tuple etc.
+    origin = _t.get_origin(tp)
+    args = _t.get_args(tp)
+
+    if origin is list or origin is _t.List:
+        if not args:
+            return "list must have an element type, e.g. list[str]"
+        return type_is_valid(args[0], additional_types, False)
+
+    if origin is dict or origin is _t.Dict:
+        if not args or len(args) != 2:
+            return "map must have exactly two type arguments, e.g. dict[str, int]"
+        key_type, value_type = args
+        if key_type is not str:
+            return f"map key type {_type_kind(key_type)} is not valid. Expected string"
+        return type_is_valid(value_type, additional_types, False)
+
+    if origin is tuple or origin is _t.Tuple:
+        if not args:
+            return "tuples must have at least one element"
+        for arg in args:
+            err = type_is_valid(arg, additional_types, False)
+            if err:
+                return err
+        return None
+
+    # bytes / bytearray
+    if _types.is_bytes(tp):
+        return None
+
+    # datetime
+    if tp is _dt.datetime or tp is _dt.date:
+        return None
+
+    # Basic scalar
+    if tp in _types.BasicTypes:
+        return None
+
+    # Cyclic structs already in additional_types
+    if tp in additional_types:
+        return None
+
+    # Sentinel for the error return type
+    if tp is _types.ErrorType:
+        if allow_error:
+            return None
+        return f"type {tp!r} is not valid as a parameter"
+
+    # Struct: dataclass or plain class
+    if isinstance(tp, type):
+        if dataclasses.is_dataclass(tp) or hasattr(tp, "__dict__"):
+            new_additional = list(additional_types) + [tp]
+            return _struct_of_valid_type(tp, new_additional)
+
+    err_str = " error," if allow_error else ""
+    return (f"type {_type_kind(tp)} is not valid. Expected a struct or one of "
+            f"the basic types{err_str} {list_basic_types()} or an array/slice of these")
+
+
+def _struct_of_valid_type(tp: Type[Any], additional_types: Sequence[Any]) -> Optional[str]:
+    """Validate each field of a struct (dataclass or plain class).
+
+    Plain classes have their ``__init__`` parameters inspected (so that
+    user-defined ``__init__`` methods can drive the schema); dataclasses are
+    inspected through their declared fields.
+    """
+    if dataclasses.is_dataclass(tp):
+        # Resolve PEP 563 string annotations to actual types.
+        try:
+            hints = _t.get_type_hints(tp)
+        except Exception:
+            hints = {}
+        fields = dataclasses.fields(tp)
+        for field in fields:
+            resolved_type = hints.get(field.name, field.type)
+            err = type_is_valid(resolved_type, additional_types, False)
+            if err:
+                return err
+        return None
+
+    # Plain class — inspect __init__ annotations if present.
+    try:
+        hints = _t.get_type_hints(tp.__init__)
+    except Exception:
+        hints = {}
+    for name, hint in hints.items():
+        if name == "self":
+            continue
+        if name == "return":
+            continue
+        err = type_is_valid(hint, additional_types, False)
+        if err:
+            return err
+    return None
+
+
+def type_matches_interface(to_match: Any, iface: Any) -> Optional[str]:
+    """Check whether *to_match* structurally satisfies the *iface* protocol.
+
+    Mirrors ``typeMatchesInterface`` from the Go implementation.  In Python we
+    rely on :class:`typing.Protocol` and :func:`typing.runtime_checkable` to
+    do this — but also fall back to method-name comparison for plain
+    :class:`abc.ABC` subclasses, which is how :class:`TransactionContextInterface`
+    is defined.
+    """
+    if iface is None:
+        return "type passed for interface is not an interface"
+    if not getattr(iface, "__abstractmethods__", None) and not _t.is_protocol(iface):
+        return "type passed for interface is not an interface"
+
+    expected_methods = getattr(iface, "__abstractmethods__", frozenset())
+    for method_name in expected_methods:
+        if not hasattr(to_match, method_name):
+            return f"missing function {method_name}"
+    return None
+
+
+def _is_protocol(tp: Any) -> bool:
+    return _t.is_protocol(tp) if hasattr(_t, "is_protocol") else False
+
+
+__all__ = [
+    "list_basic_types",
+    "type_is_valid",
+    "type_matches_interface",
+]

src/fabric_contract_api/internal/utils.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Internal helper utilities used throughout :mod:`fabric_contract_api`.
+
+These helpers are the Python equivalent of the helpers in Go's
+``fabric-contract-api-go/internal/utils`` package.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, List, Sequence
+
+
+def string_in_slice(needle: str, haystack: Sequence[str]) -> bool:
+    """Return ``True`` if *needle* is in *haystack*.
+
+    Mirrors ``utils.StringInSlice`` from the Go implementation.
+    """
+    return needle in haystack
+
+
+def slice_as_comma_sentence(items: Sequence[str]) -> str:
+    """Format *items* as a comma-separated "and" sentence.
+
+    Mirrors ``utils.SliceAsCommaSentence`` from the Go implementation, e.g.::
+
+        ["a"]            -> "a"
+        ["a", "b"]       -> "a and b"
+        ["a", "b", "c"]  -> "a, b and c"
+    """
+    items = list(items)
+    if not items:
+        return ""
+    if len(items) == 1:
+        return items[0]
+    if len(items) == 2:
+        return f"{items[0]} and {items[1]}"
+    head = ", ".join(items[:-1])
+    return f"{head} and {items[-1]}"
+
+
+def validate_errors_to_string(errors: Iterable[str]) -> str:
+    """Convert a list of JSON-schema validation errors into a readable string.
+
+    Mirrors ``utils.ValidateErrorsToString`` from the Go implementation.  The
+    errors are sorted lexicographically and numbered 1..N.
+    """
+    sorted_errors: List[str] = sorted(str(e) for e in errors)
+    if not sorted_errors:
+        return ""
+    return "\n".join(
+        f"{i + 1}. {err}" for i, err in enumerate(sorted_errors)
+    )
+
+
+__all__ = [
+    "string_in_slice",
+    "slice_as_comma_sentence",
+    "validate_errors_to_string",
+]

src/fabric_contract_api/metadata/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Metadata package for :mod:`fabric_contract_api`.
+
+Mirrors Go's ``metadata`` package: dataclasses describing the contract
+chaincode metadata, JSON-schema helpers, and the embedded schema used to
+validate user-supplied metadata files.
+"""
+
+# Import the metadata dataclasses and helpers eagerly.  ``schema.py`` is
+# imported lazily (via ``from .schema import get_schema``) by callers that
+# actually need it to avoid a circular import with the ``internal`` package.
+from .metadata import (  # noqa: F401
+    ComponentMetadata,
+    ContactMetadata,
+    ContractChaincodeMetadata,
+    ContractMetadata,
+    InfoMetadata,
+    LicenseMetadata,
+    ObjectMetadata,
+    ParameterMetadata,
+    ReturnMetadata,
+    TransactionMetadata,
+    get_json_schema,
+    read_metadata_file,
+    validate_against_schema,
+)
+
+
+def get_schema(field_type, components):  # pragma: no cover - thin proxy
+    """Lazy re-export of :func:`fabric_contract_api.metadata.schema.get_schema`."""
+    from .schema import get_schema as _impl
+    return _impl(field_type, components)