pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/yoga/yoga/style/StyleLength.h

@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <yoga/enums/Unit.h>
+#include <yoga/numeric/FloatOptional.h>
+
+namespace facebook::yoga {
+
+/**
+ * Style::Length represents a CSS Value which may be one of:
+ * 1. Undefined
+ * 2. A keyword (e.g. auto)
+ * 3. A CSS <length-percentage> value:
+ *    a. <length> value (e.g. 10px)
+ *    b. <percentage> value of a reference <length>
+ * 4. (soon) A math function which returns a <length-percentage> value
+ *
+ * References:
+ * 1. https://www.w3.org/TR/css-values-4/#lengths
+ * 2. https://www.w3.org/TR/css-values-4/#percentage-value
+ * 3. https://www.w3.org/TR/css-values-4/#mixed-percentages
+ * 4. https://www.w3.org/TR/css-values-4/#math
+ */
+class StyleLength {
+ public:
+  constexpr StyleLength() = default;
+
+  constexpr static StyleLength points(float value) {
+    return yoga::isUndefined(value) || yoga::isinf(value)
+        ? undefined()
+        : StyleLength{FloatOptional{value}, Unit::Point};
+  }
+
+  constexpr static StyleLength percent(float value) {
+    return yoga::isUndefined(value) || yoga::isinf(value)
+        ? undefined()
+        : StyleLength{FloatOptional{value}, Unit::Percent};
+  }
+
+  constexpr static StyleLength ofAuto() {
+    return StyleLength{{}, Unit::Auto};
+  }
+
+  constexpr static StyleLength undefined() {
+    return StyleLength{{}, Unit::Undefined};
+  }
+
+  constexpr bool isAuto() const {
+    return unit_ == Unit::Auto;
+  }
+
+  constexpr bool isUndefined() const {
+    return unit_ == Unit::Undefined;
+  }
+
+  constexpr bool isDefined() const {
+    return !isUndefined();
+  }
+
+  constexpr FloatOptional value() const {
+    return value_;
+  }
+
+  constexpr Unit unit() const {
+    return unit_;
+  }
+
+  constexpr FloatOptional resolve(float referenceLength) {
+    switch (unit_) {
+      case Unit::Point:
+        return value_;
+      case Unit::Percent:
+        return FloatOptional{value_.unwrap() * referenceLength * 0.01f};
+      default:
+        return FloatOptional{};
+    }
+  }
+
+  explicit constexpr operator YGValue() const {
+    return YGValue{value_.unwrap(), unscopedEnum(unit_)};
+  }
+
+  constexpr bool operator==(const StyleLength& rhs) const {
+    return value_ == rhs.value_ && unit_ == rhs.unit_;
+  }
+
+ private:
+  // We intentionally do not allow direct construction using value and unit, to
+  // avoid invalid, or redundant combinations.
+  constexpr StyleLength(FloatOptional value, Unit unit)
+      : value_(value), unit_(unit) {}
+
+  FloatOptional value_{};
+  Unit unit_{Unit::Undefined};
+};
+
+inline bool inexactEquals(const StyleLength& a, const StyleLength& b) {
+  return a.unit() == b.unit() && inexactEquals(a.value(), b.value());
+}
+
+} // namespace facebook::yoga

pythonnative/native/yoga/yoga/style/StyleValueHandle.h

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cstdint>
+
+#include <yoga/Yoga.h>
+
+#include <yoga/numeric/FloatOptional.h>
+#include <yoga/style/SmallValueBuffer.h>
+#include <yoga/style/StyleLength.h>
+
+namespace facebook::yoga {
+
+#pragma pack(push)
+#pragma pack(1)
+
+/**
+ * StyleValueHandle is a small (16-bit) handle to a length or number in a style.
+ * The value may be embedded directly in the handle if simple, or the handle may
+ * instead point to an index within a StyleValuePool.
+ *
+ * To read or write a value from a StyleValueHandle, use
+ * `StyleValuePool::store()`, and `StyleValuePool::getLength()`/
+ * `StyleValuePool::getNumber()`.
+ */
+class StyleValueHandle {
+ public:
+  static constexpr StyleValueHandle ofAuto() {
+    StyleValueHandle handle;
+    handle.setType(Type::Auto);
+    return handle;
+  }
+
+  constexpr bool isUndefined() const {
+    return type() == Type::Undefined;
+  }
+
+  constexpr bool isDefined() const {
+    return !isUndefined();
+  }
+
+  constexpr bool isAuto() const {
+    return type() == Type::Auto;
+  }
+
+ private:
+  friend class StyleValuePool;
+
+  static constexpr uint16_t kHandleTypeMask = 0b0000'0000'0000'0111;
+  static constexpr uint16_t kHandleIndexedMask = 0b0000'0000'0000'1000;
+  static constexpr uint16_t kHandleValueMask = 0b1111'1111'1111'0000;
+
+  enum class Type : uint8_t {
+    Undefined,
+    Point,
+    Percent,
+    Number,
+    Auto,
+  };
+
+  constexpr Type type() const {
+    return static_cast<Type>(repr_ & kHandleTypeMask);
+  }
+
+  constexpr void setType(Type handleType) {
+    repr_ &= (~kHandleTypeMask);
+    repr_ |= static_cast<uint8_t>(handleType);
+  }
+
+  constexpr uint16_t value() const {
+    return repr_ >> 4;
+  }
+
+  constexpr void setValue(uint16_t value) {
+    repr_ &= (~kHandleValueMask);
+    repr_ |= (value << 4);
+  }
+
+  constexpr bool isValueIndexed() const {
+    return (repr_ & kHandleIndexedMask) != 0;
+  }
+
+  constexpr void setValueIsIndexed() {
+    repr_ |= kHandleIndexedMask;
+  }
+
+  uint16_t repr_{0};
+};
+
+#pragma pack(pop)
+
+} // namespace facebook::yoga

pythonnative/native/yoga/yoga/style/StyleValuePool.h

@@ -0,0 +1,127 @@
+/*
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#pragma once
+
+#include <cassert>
+#include <cstdint>
+
+#include <yoga/numeric/FloatOptional.h>
+#include <yoga/style/SmallValueBuffer.h>
+#include <yoga/style/StyleLength.h>
+#include <yoga/style/StyleValueHandle.h>
+
+namespace facebook::yoga {
+
+/**
+ * StyleValuePool allows compact storage for a sparse collection of assigned
+ * lengths and numbers. Values are referred to using StyleValueHandle. In most
+ * cases StyleValueHandle can embed the value directly, but if not, the value is
+ * stored within a buffer provided by the pool. The pool contains a fixed number
+ * of inline slots before falling back to heap allocating additional slots.
+ */
+class StyleValuePool {
+ public:
+  void store(StyleValueHandle& handle, StyleLength length) {
+    if (length.isUndefined()) {
+      handle.setType(StyleValueHandle::Type::Undefined);
+    } else if (length.isAuto()) {
+      handle.setType(StyleValueHandle::Type::Auto);
+    } else {
+      auto type = length.unit() == Unit::Point
+          ? StyleValueHandle::Type::Point
+          : StyleValueHandle::Type::Percent;
+      storeValue(handle, length.value().unwrap(), type);
+    }
+  }
+
+  void store(StyleValueHandle& handle, FloatOptional number) {
+    if (number.isUndefined()) {
+      handle.setType(StyleValueHandle::Type::Undefined);
+    } else {
+      storeValue(handle, number.unwrap(), StyleValueHandle::Type::Number);
+    }
+  }
+
+  StyleLength getLength(StyleValueHandle handle) const {
+    if (handle.isUndefined()) {
+      return StyleLength::undefined();
+    } else if (handle.isAuto()) {
+      return StyleLength::ofAuto();
+    } else {
+      assert(
+          handle.type() == StyleValueHandle::Type::Point ||
+          handle.type() == StyleValueHandle::Type::Percent);
+      float value = (handle.isValueIndexed())
+          ? std::bit_cast<float>(buffer_.get32(handle.value()))
+          : unpackInlineInteger(handle.value());
+
+      return handle.type() == StyleValueHandle::Type::Point
+          ? StyleLength::points(value)
+          : StyleLength::percent(value);
+    }
+  }
+
+  FloatOptional getNumber(StyleValueHandle handle) const {
+    if (handle.isUndefined()) {
+      return FloatOptional{};
+    } else {
+      assert(handle.type() == StyleValueHandle::Type::Number);
+      float value = (handle.isValueIndexed())
+          ? std::bit_cast<float>(buffer_.get32(handle.value()))
+          : unpackInlineInteger(handle.value());
+      return FloatOptional{value};
+    }
+  }
+
+ private:
+  void storeValue(
+      StyleValueHandle& handle,
+      float value,
+      StyleValueHandle::Type type) {
+    handle.setType(type);
+
+    if (handle.isValueIndexed()) {
+      auto newIndex =
+          buffer_.replace(handle.value(), std::bit_cast<uint32_t>(value));
+      handle.setValue(newIndex);
+    } else if (isIntegerPackable(value)) {
+      handle.setValue(packInlineInteger(value));
+    } else {
+      auto newIndex = buffer_.push(std::bit_cast<uint32_t>(value));
+      handle.setValue(newIndex);
+      handle.setValueIsIndexed();
+    }
+  }
+
+  static constexpr bool isIntegerPackable(float f) {
+    constexpr uint16_t kMaxInlineAbsValue = (1 << 11) - 1;
+
+    auto i = static_cast<int32_t>(f);
+    return static_cast<float>(i) == f && i >= -kMaxInlineAbsValue &&
+        i <= +kMaxInlineAbsValue;
+  }
+
+  static constexpr uint16_t packInlineInteger(float value) {
+    uint16_t isNegative = value < 0 ? 1 : 0;
+    return static_cast<uint16_t>(
+        (isNegative << 11) |
+        (static_cast<int32_t>(value) * (isNegative != 0u ? -1 : 1)));
+  }
+
+  static constexpr float unpackInlineInteger(uint16_t value) {
+    constexpr uint16_t kValueSignMask = 0b0000'1000'0000'0000;
+    constexpr uint16_t kValueMagnitudeMask = 0b0000'0111'1111'1111;
+    const bool isNegative = (value & kValueSignMask) != 0;
+    return static_cast<float>(
+        (value & kValueMagnitudeMask) * (isNegative ? -1 : 1));
+  }
+
+  SmallValueBuffer<4> buffer_;
+};
+
+} // namespace facebook::yoga

pythonnative/native_modules/__init__.py

@@ -0,0 +1,124 @@
+"""Native API modules for device capabilities.
+
+Cross-platform Python interfaces to common device APIs. Every module
+here is a thin facade over a *native module*: a Swift class in
+``PythonNativeKit`` and a Kotlin class in the ``pythonnative`` Gradle
+module registered under the same name (``"Camera"``, ``"Haptics"``,
+...). Facades reach them through
+[`native_module`][pythonnative.native_modules.registry.native_module]
+and the bridge described in ``docs/concepts/bridge.md``; there is no
+Python-side Objective-C or JNI anywhere in this package.
+
+Off device the same names resolve to plain Python implementations in
+[`pythonnative.native_modules.fallback`][pythonnative.native_modules.fallback]
+with safe defaults (in-memory buffers, ``"unknown"`` states, no-op
+feedback), so the same code stays runnable in unit tests. The browser
+preview (``pn start``) implements the modules a browser can honor
+(``Alert``, ``Clipboard``, ``Device``, ``Linking``, ``Share``, ...) in
+the page and falls back to the Python classes for the rest. Third-party
+packages ship their own native modules the same way; see
+``docs/guides/native-modules.md``.
+
+Two rules hold across every facade, so you never have to look one up:
+
+1. **Sync or async is decided by what the OS has to do.** A method is
+   a plain function when the answer is already on the device and
+   returns on the calling thread (read the pasteboard, check a
+   permission, read the battery level, Keychain get/set, file I/O).
+   It is a coroutine when the OS has to prompt the user, drive
+   hardware, or hand off to another process (camera and gallery
+   pickers, biometric prompts, permission requests, the share sheet,
+   GPS fixes, notification scheduling, remote push registration).
+2. **Failures raise; "nothing happened" returns a value.** A native
+   error (a rejected promise, a missing module, a bad argument) is a
+   [`NativeModuleError`][pythonnative.native_modules.NativeModuleError]
+   and propagates to the caller like any other Python exception. Outcomes
+   that are not errors, such as the user cancelling a picker, denying a
+   permission, or dismissing the share sheet, come back as ``None``,
+   ``False``, or a status string, and are documented per method. No
+   facade converts an exception into a default value.
+
+Hardware / media:
+
+- [`Camera`][pythonnative.native_modules.Camera]: photo capture and
+  gallery picking.
+- [`Location`][pythonnative.native_modules.Location]: GPS and location.
+- [`Battery`][pythonnative.native_modules.Battery]: charge level/state.
+- [`Haptics`][pythonnative.native_modules.Haptics] /
+  [`Vibration`][pythonnative.native_modules.Vibration]: tactile feedback.
+- [`Biometrics`][pythonnative.native_modules.Biometrics]: Face ID /
+  Touch ID / fingerprint auth.
+
+System integration:
+
+- [`FileSystem`][pythonnative.native_modules.FileSystem]: app-scoped
+  file I/O.
+- [`Notifications`][pythonnative.native_modules.Notifications]: local
+  push notifications.
+- [`Clipboard`][pythonnative.native_modules.Clipboard]: pasteboard
+  read/write.
+- [`Share`][pythonnative.native_modules.Share]: system share sheet.
+- [`Linking`][pythonnative.native_modules.Linking]: open URLs and deep
+  links.
+- [`Permissions`][pythonnative.native_modules.Permissions]: runtime
+  permission checks/requests.
+- [`SecureStore`][pythonnative.native_modules.SecureStore]: encrypted
+  secret storage.
+
+Reactive state (with hooks):
+
+- [`AppState`][pythonnative.native_modules.AppState] +
+  [`use_app_state`][pythonnative.use_app_state]: foreground/background
+  lifecycle.
+- [`NetInfo`][pythonnative.native_modules.NetInfo] +
+  [`use_net_info`][pythonnative.use_net_info]: connectivity.
+"""
+
+from .app_state import AppState, use_app_state
+from .battery import Battery
+from .biometrics import Biometrics
+from .camera import Camera
+from .clipboard import Clipboard
+from .file_system import FileSystem
+from .haptics import Haptics, Vibration
+from .linking import Linking
+from .location import Location
+from .net_info import NetInfo, use_net_info
+from .notifications import Notifications
+from .permissions import Permissions
+from .registry import (
+    BridgeModule,
+    NativeModule,
+    NativeModuleError,
+    PythonModule,
+    native_module,
+    register_python_module,
+)
+from .secure_store import SecureStore
+from .share import Share
+
+__all__ = [
+    "AppState",
+    "Battery",
+    "Biometrics",
+    "BridgeModule",
+    "Camera",
+    "Clipboard",
+    "FileSystem",
+    "Haptics",
+    "Linking",
+    "Location",
+    "NativeModule",
+    "NativeModuleError",
+    "NetInfo",
+    "Notifications",
+    "Permissions",
+    "PythonModule",
+    "SecureStore",
+    "Share",
+    "Vibration",
+    "native_module",
+    "register_python_module",
+    "use_app_state",
+    "use_net_info",
+]

pythonnative/native_modules/app_state.py

@@ -0,0 +1,99 @@
+"""Foreground / background app lifecycle state.
+
+[`AppState`][pythonnative.AppState] exposes the current lifecycle phase
+(``"active"``, ``"inactive"``, or ``"background"``) and lets you
+subscribe to transitions. The native ``AppState`` module pushes a
+``change`` event on every transition; off device, tests drive the same
+path through
+[`dispatch_app_state`][pythonnative.native_modules.app_state.dispatch_app_state].
+
+Prefer the [`use_app_state`][pythonnative.use_app_state] hook inside
+components; use the imperative API for non-UI code.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    @pn.component
+    def Banner():
+        state = pn.use_app_state()
+        return pn.Text(f"App is {state}")
+    ```
+"""
+
+from __future__ import annotations
+
+from typing import Callable, List
+
+from .. import diagnostics
+from ..hooks import use_effect, use_state
+from .registry import on_event
+
+AppStateStatus = str  # "active" | "inactive" | "background"
+
+_VALID = ("active", "inactive", "background")
+_current: AppStateStatus = "active"
+_listeners: List[Callable[[AppStateStatus], None]] = []
+
+
+class AppState:
+    """App lifecycle state interface."""
+
+    @staticmethod
+    def current_state() -> AppStateStatus:
+        """Return the current lifecycle phase."""
+        return _current
+
+    @staticmethod
+    def add_listener(callback: Callable[[AppStateStatus], None]) -> Callable[[], None]:
+        """Subscribe to lifecycle changes.
+
+        Returns:
+            A zero-arg function that unsubscribes when called.
+        """
+        _listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            try:
+                _listeners.remove(callback)
+            except ValueError:
+                pass
+
+        return _unsubscribe
+
+
+def dispatch_app_state(state: AppStateStatus) -> None:
+    """Update the current state and notify every listener.
+
+    Unknown values are ignored so a misbehaving host can't push garbage
+    into the tree.
+    """
+    global _current
+    if state not in _VALID or state == _current:
+        return
+    _current = state
+    for listener in list(_listeners):
+        try:
+            listener(state)
+        except Exception:
+            diagnostics.swallowed("app_state.dispatch_app_state")
+
+
+on_event("AppState", "change", lambda payload: dispatch_app_state(str(payload)))
+
+
+def use_app_state() -> AppStateStatus:
+    """Subscribe a component to [`AppState`][pythonnative.AppState].
+
+    Returns:
+        The current lifecycle phase; the component re-renders whenever
+        it changes.
+    """
+    state, set_state = use_state(_current)
+
+    def _subscribe() -> Callable[[], None]:
+        set_state(_current)
+        return AppState.add_listener(set_state)
+
+    use_effect(_subscribe, [])
+    return state

pythonnative/native_modules/battery.py

@@ -0,0 +1,75 @@
+"""Battery level and charging state.
+
+[`Battery`][pythonnative.Battery] reports the current charge fraction
+(``0.0`` to ``1.0``, or ``-1.0`` when the platform doesn't know) and
+charging state, and lets you subscribe to changes. Both getters read a
+value the OS already holds, so they are synchronous. The native
+``Battery`` module pushes a ``change`` event with ``{"level", "state"}``;
+off device, tests drive the same path through
+[`dispatch_battery`][pythonnative.native_modules.battery.dispatch_battery].
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List
+
+from .. import diagnostics
+from .registry import native_module, on_event
+
+BatteryState = str  # "unknown" | "unplugged" | "charging" | "full"
+
+_listeners: List[Callable[[Dict[str, object]], None]] = []
+
+
+class Battery:
+    """Battery interface (synchronous getters + change listener).
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
+
+    @staticmethod
+    def get_level() -> float:
+        """Return the charge fraction in ``[0, 1]``, or ``-1.0`` when the platform can't report it."""
+        level = float(native_module("Battery").call("get_level"))
+        return level if 0.0 <= level <= 1.0 else -1.0
+
+    @staticmethod
+    def get_state() -> BatteryState:
+        """Return ``"charging"`` / ``"full"`` / ``"unplugged"`` / ``"unknown"``."""
+        state = str(native_module("Battery").call("get_state") or "unknown")
+        return state if state in ("unknown", "unplugged", "charging", "full") else "unknown"
+
+    @staticmethod
+    def add_listener(callback: Callable[[Dict[str, object]], None]) -> Callable[[], None]:
+        """Subscribe to battery changes; returns an unsubscribe fn.
+
+        Each callback receives ``{"level": float, "state": str}``.
+        """
+        _listeners.append(callback)
+
+        def _unsubscribe() -> None:
+            try:
+                _listeners.remove(callback)
+            except ValueError:
+                pass
+
+        return _unsubscribe
+
+
+def dispatch_battery(level: float, state: BatteryState) -> None:
+    """Notify listeners of a battery change."""
+    payload: Dict[str, object] = {"level": level, "state": state}
+    for listener in list(_listeners):
+        try:
+            listener(dict(payload))
+        except Exception:
+            diagnostics.swallowed("battery.dispatch_battery")
+
+
+def _on_native_change(payload: Any) -> None:
+    if isinstance(payload, dict):
+        dispatch_battery(float(payload.get("level", -1.0)), str(payload.get("state", "unknown")))
+
+
+on_event("Battery", "change", _on_native_change)

pythonnative/native_modules/biometrics.py

@@ -0,0 +1,42 @@
+"""Biometric authentication (Face ID / Touch ID / fingerprint).
+
+[`Biometrics`][pythonnative.Biometrics] gates an action behind the
+device's biometric hardware via ``LAContext`` (iOS) and
+``BiometricPrompt`` (Android), both implemented in the native
+``Biometrics`` module.
+
+``is_available`` is synchronous (a capability lookup); ``authenticate``
+is a coroutine that presents the system prompt and resolves to ``True``
+on success or ``False`` when the user fails or cancels the prompt.
+
+Example:
+    ```python
+    import pythonnative as pn
+
+    async def unlock():
+        if await pn.Biometrics.authenticate("Unlock your vault"):
+            show_secrets()
+    ```
+"""
+
+from __future__ import annotations
+
+from .registry import native_module
+
+
+class Biometrics:
+    """Biometric authentication interface.
+
+    Raises:
+        NativeModuleError: If the native module fails.
+    """
+
+    @staticmethod
+    def is_available() -> bool:
+        """Return ``True`` when biometric auth can be attempted (enrolled hardware; ``False`` off device)."""
+        return bool(native_module("Biometrics").call("is_available"))
+
+    @staticmethod
+    async def authenticate(reason: str = "Authenticate") -> bool:
+        """Present the biometric prompt; resolve ``True`` on success, ``False`` on failure or cancel."""
+        return bool(await native_module("Biometrics").call_async("authenticate", reason=reason))