yoga-layout-python 0.1.0__py3-none-any.whl

yoga/style/StyleLength.py

@@ -0,0 +1,88 @@
+"""
+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.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..YGEnums import YGUnit
+from ..YGValue import YGValue
+from ..numeric.FloatMath import float32
+from ..numeric.FloatOptional import FloatOptional, inexactEquals as inexactEqualsFloatOptional
+from ..numeric.Comparison import isUndefined, isinf
+
+
+@dataclass(frozen=True)
+class StyleLength:
+    value_: FloatOptional = FloatOptional()
+    unit_: YGUnit = YGUnit.YGUnitUndefined
+
+    @staticmethod
+    def points(value: float) -> "StyleLength":
+        return (
+            StyleLength.undefined()
+            if isUndefined(value) or isinf(value)
+            else StyleLength(FloatOptional(value), YGUnit.YGUnitPoint)
+        )
+
+    @staticmethod
+    def percent(value: float) -> "StyleLength":
+        return (
+            StyleLength.undefined()
+            if isUndefined(value) or isinf(value)
+            else StyleLength(FloatOptional(value), YGUnit.YGUnitPercent)
+        )
+
+    @staticmethod
+    def ofAuto() -> "StyleLength":
+        return StyleLength(FloatOptional(), YGUnit.YGUnitAuto)
+
+    @staticmethod
+    def undefined() -> "StyleLength":
+        return StyleLength(FloatOptional(), YGUnit.YGUnitUndefined)
+
+    def isAuto(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitAuto
+
+    def isUndefined(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitUndefined
+
+    def isPoints(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitPoint
+
+    def isPercent(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitPercent
+
+    def isDefined(self) -> bool:
+        return not self.isUndefined()
+
+    def value(self) -> FloatOptional:
+        return self.value_
+
+    def resolve(self, referenceLength: float) -> FloatOptional:
+        if self.unit_ == YGUnit.YGUnitPoint:
+            return self.value_
+        if self.unit_ == YGUnit.YGUnitPercent:
+            return FloatOptional(
+                float32(
+                    float32(float32(self.value_.unwrap()) * float32(referenceLength))
+                    * float32(0.01)
+                )
+            )
+        return FloatOptional()
+
+    def asYGValue(self) -> YGValue:
+        return YGValue(self.value_.unwrap(), self.unit_)
+
+    def inexactEquals(self, other: "StyleLength") -> bool:
+        return self.unit_ == other.unit_ and inexactEqualsFloatOptional(
+            self.value_, other.value_
+        )
+
+
+def inexactEquals(a: StyleLength, b: StyleLength) -> bool:
+    return a.inexactEquals(b)

yoga/style/StyleSizeLength.py

@@ -0,0 +1,117 @@
+"""
+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.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..YGEnums import YGUnit
+from ..YGValue import YGValue
+from ..numeric.FloatMath import float32
+from ..numeric.FloatOptional import FloatOptional, inexactEquals as inexactEqualsFloatOptional
+from ..numeric.Comparison import isUndefined, isinf
+
+
+@dataclass(frozen=True)
+class StyleSizeLength:
+    value_: FloatOptional = FloatOptional()
+    unit_: YGUnit = YGUnit.YGUnitUndefined
+
+    @staticmethod
+    def points(value: float) -> "StyleSizeLength":
+        return (
+            StyleSizeLength.undefined()
+            if isUndefined(value) or isinf(value)
+            else StyleSizeLength(FloatOptional(value), YGUnit.YGUnitPoint)
+        )
+
+    @staticmethod
+    def percent(value: float) -> "StyleSizeLength":
+        return (
+            StyleSizeLength.undefined()
+            if isUndefined(value) or isinf(value)
+            else StyleSizeLength(FloatOptional(value), YGUnit.YGUnitPercent)
+        )
+
+    @staticmethod
+    def stretch(fraction: float) -> "StyleSizeLength":
+        return (
+            StyleSizeLength.undefined()
+            if isUndefined(fraction) or isinf(fraction)
+            else StyleSizeLength(FloatOptional(fraction), YGUnit.YGUnitStretch)
+        )
+
+    @staticmethod
+    def ofAuto() -> "StyleSizeLength":
+        return StyleSizeLength(FloatOptional(), YGUnit.YGUnitAuto)
+
+    @staticmethod
+    def ofMaxContent() -> "StyleSizeLength":
+        return StyleSizeLength(FloatOptional(), YGUnit.YGUnitMaxContent)
+
+    @staticmethod
+    def ofFitContent() -> "StyleSizeLength":
+        return StyleSizeLength(FloatOptional(), YGUnit.YGUnitFitContent)
+
+    @staticmethod
+    def ofStretch() -> "StyleSizeLength":
+        return StyleSizeLength(FloatOptional(), YGUnit.YGUnitStretch)
+
+    @staticmethod
+    def undefined() -> "StyleSizeLength":
+        return StyleSizeLength(FloatOptional(), YGUnit.YGUnitUndefined)
+
+    def isAuto(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitAuto
+
+    def isMaxContent(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitMaxContent
+
+    def isFitContent(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitFitContent
+
+    def isStretch(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitStretch
+
+    def isUndefined(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitUndefined
+
+    def isDefined(self) -> bool:
+        return not self.isUndefined()
+
+    def isPoints(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitPoint
+
+    def isPercent(self) -> bool:
+        return self.unit_ == YGUnit.YGUnitPercent
+
+    def value(self) -> FloatOptional:
+        return self.value_
+
+    def resolve(self, referenceLength: float) -> FloatOptional:
+        if self.unit_ == YGUnit.YGUnitPoint:
+            return self.value_
+        if self.unit_ == YGUnit.YGUnitPercent:
+            return FloatOptional(
+                float32(
+                    float32(float32(self.value_.unwrap()) * float32(referenceLength))
+                    * float32(0.01)
+                )
+            )
+        return FloatOptional()
+
+    def asYGValue(self) -> YGValue:
+        return YGValue(self.value_.unwrap(), self.unit_)
+
+    def inexactEquals(self, other: "StyleSizeLength") -> bool:
+        return self.unit_ == other.unit_ and inexactEqualsFloatOptional(
+            self.value_, other.value_
+        )
+
+
+def inexactEquals(a: StyleSizeLength, b: StyleSizeLength) -> bool:
+    return a.inexactEquals(b)

yoga/style/StyleValueHandle.py

@@ -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.
+"""
+
+from __future__ import annotations
+
+
+class StyleValueHandle:
+    """
+    A compact (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.
+    """
+
+    # Bit masks for handle encoding
+    HANDLE_TYPE_MASK = 0b0000_0000_0000_0111
+    HANDLE_INDEXED_MASK = 0b0000_0000_0000_1000
+    HANDLE_VALUE_MASK = 0b1111_1111_1111_0000
+
+    class Type:
+        Undefined = 0
+        Point = 1
+        Percent = 2
+        Number = 3
+        Auto = 4
+        Keyword = 5
+
+    class Keyword:
+        MaxContent = 0
+        FitContent = 1
+        Stretch = 2
+
+    def __init__(self, repr_: int = 0) -> None:
+        self._repr = repr_
+
+    @classmethod
+    def ofAuto(cls) -> "StyleValueHandle":
+        """Create a handle representing 'auto'."""
+        handle = cls()
+        handle._set_type(cls.Type.Auto)
+        return handle
+
+    @classmethod
+    def ofUndefined(cls) -> "StyleValueHandle":
+        """Create a handle representing 'undefined'."""
+        handle = cls()
+        handle._set_type(cls.Type.Undefined)
+        return handle
+
+    def isUndefined(self) -> bool:
+        """Check if the handle represents undefined."""
+        return self._type() == self.Type.Undefined
+
+    def isDefined(self) -> bool:
+        """Check if the handle represents a defined value."""
+        return not self.isUndefined()
+
+    def isAuto(self) -> bool:
+        """Check if the handle represents 'auto'."""
+        return self._type() == self.Type.Auto
+
+    def _type(self) -> int:
+        """Get the type encoded in the handle."""
+        return self._repr & self.HANDLE_TYPE_MASK
+
+    def _set_type(self, handle_type: int) -> None:
+        """Set the type in the handle."""
+        self._repr &= ~self.HANDLE_TYPE_MASK
+        self._repr |= handle_type
+
+    def _value(self) -> int:
+        """Get the value encoded in the handle."""
+        return self._repr >> 4
+
+    def _set_value(self, value: int) -> None:
+        """Set the value in the handle."""
+        self._repr &= ~self.HANDLE_VALUE_MASK
+        self._repr |= (value << 4)
+
+    def isValueIndexed(self) -> bool:
+        """Check if the value is stored in an index."""
+        return (self._repr & self.HANDLE_INDEXED_MASK) != 0
+
+    def setValueIsIndexed(self) -> None:
+        """Mark the value as indexed."""
+        self._repr |= self.HANDLE_INDEXED_MASK
+
+    def clearValueIsIndexed(self) -> None:
+        """Mark the value as inline, not indexed."""
+        self._repr &= ~self.HANDLE_INDEXED_MASK
+
+    def isKeyword(self, keyword: int) -> bool:
+        """Check if the handle represents a specific keyword."""
+        return self._type() == self.Type.Keyword and self._value() == keyword

yoga/style/StyleValuePool.py

@@ -0,0 +1,191 @@
+"""
+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.
+"""
+
+from __future__ import annotations
+
+import struct
+from typing import Optional
+
+from .SmallValueBuffer import SmallValueBuffer
+from .StyleLength import StyleLength
+from .StyleSizeLength import StyleSizeLength
+from .StyleValueHandle import StyleValueHandle
+from ..numeric.FloatOptional import FloatOptional
+
+
+class StyleValuePool:
+    """
+    Pool for compact storage of sparse 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.
+    """
+
+    # Number of inline slots before falling back to heap allocation
+    INLINE_BUFFER_SIZE = 4
+
+    def __init__(self) -> None:
+        self._buffer = SmallValueBuffer(buffer_size=self.INLINE_BUFFER_SIZE)
+
+    def store_length(self, handle: StyleValueHandle, length: StyleLength) -> None:
+        """Store a StyleLength in the handle."""
+        if length.isUndefined():
+            handle._set_type(StyleValueHandle.Type.Undefined)
+            handle.clearValueIsIndexed()
+        elif length.isAuto():
+            handle._set_type(StyleValueHandle.Type.Auto)
+            handle.clearValueIsIndexed()
+        else:
+            type_ = (
+                StyleValueHandle.Type.Point
+                if length.isPoints()
+                else StyleValueHandle.Type.Percent
+            )
+            self._store_value(handle, length.value().unwrap(), type_)
+
+    def store_size(self, handle: StyleValueHandle, size_value: StyleSizeLength) -> None:
+        """Store a StyleSizeLength in the handle."""
+        if size_value.isUndefined():
+            handle._set_type(StyleValueHandle.Type.Undefined)
+            handle.clearValueIsIndexed()
+        elif size_value.isAuto():
+            handle._set_type(StyleValueHandle.Type.Auto)
+            handle.clearValueIsIndexed()
+        elif size_value.isMaxContent():
+            self._store_keyword(handle, StyleValueHandle.Keyword.MaxContent)
+        elif size_value.isStretch():
+            self._store_keyword(handle, StyleValueHandle.Keyword.Stretch)
+        elif size_value.isFitContent():
+            self._store_keyword(handle, StyleValueHandle.Keyword.FitContent)
+        else:
+            type_ = (
+                StyleValueHandle.Type.Point
+                if size_value.isPoints()
+                else StyleValueHandle.Type.Percent
+            )
+            self._store_value(handle, size_value.value().unwrap(), type_)
+
+    def store_number(
+        self, handle: StyleValueHandle, number: FloatOptional
+    ) -> None:
+        """Store a number in the handle."""
+        if number.isUndefined():
+            handle._set_type(StyleValueHandle.Type.Undefined)
+            handle.clearValueIsIndexed()
+        else:
+            self._store_value(handle, number.unwrap(), StyleValueHandle.Type.Number)
+
+    def get_length(self, handle: StyleValueHandle) -> StyleLength:
+        """Get a StyleLength from the handle."""
+        if handle.isUndefined():
+            return StyleLength.undefined()
+        elif handle.isAuto():
+            return StyleLength.ofAuto()
+        else:
+            value = self._get_float_value(handle)
+            if handle._type() == StyleValueHandle.Type.Point:
+                return StyleLength.points(value)
+            else:
+                return StyleLength.percent(value)
+
+    def get_size(self, handle: StyleValueHandle) -> StyleSizeLength:
+        """Get a StyleSizeLength from the handle."""
+        if handle.isUndefined():
+            return StyleSizeLength.undefined()
+        elif handle.isAuto():
+            return StyleSizeLength.ofAuto()
+        elif handle.isKeyword(StyleValueHandle.Keyword.MaxContent):
+            return StyleSizeLength.ofMaxContent()
+        elif handle.isKeyword(StyleValueHandle.Keyword.FitContent):
+            return StyleSizeLength.ofFitContent()
+        elif handle.isKeyword(StyleValueHandle.Keyword.Stretch):
+            return StyleSizeLength.ofStretch()
+        else:
+            value = self._get_float_value(handle)
+            if handle._type() == StyleValueHandle.Type.Point:
+                return StyleSizeLength.points(value)
+            else:
+                return StyleSizeLength.percent(value)
+
+    def get_number(self, handle: StyleValueHandle) -> FloatOptional:
+        """Get a number from the handle."""
+        if handle.isUndefined():
+            return FloatOptional()
+        else:
+            value = self._get_float_value(handle)
+            return FloatOptional(value)
+
+    def _store_value(
+        self, handle: StyleValueHandle, value: float, type_: int
+    ) -> None:
+        """Store a float value in the handle."""
+        handle._set_type(type_)
+
+        if self._is_integer_packable(value):
+            if handle.isValueIndexed():
+                handle.clearValueIsIndexed()
+            handle._set_value(self._pack_inline_integer(value))
+        else:
+            packed = struct.pack("<f", value)
+            int_value = struct.unpack("<I", packed)[0]
+            new_index = (
+                self._buffer.replace(handle._value(), int_value)
+                if handle.isValueIndexed()
+                else self._buffer.push(int_value)
+            )
+            handle._set_value(new_index)
+            handle.setValueIsIndexed()
+
+    def _store_keyword(
+        self, handle: StyleValueHandle, keyword: int
+    ) -> None:
+        """Store a keyword in the handle."""
+        handle._set_type(StyleValueHandle.Type.Keyword)
+        if handle.isValueIndexed():
+            new_index = self._buffer.replace(handle._value(), keyword)
+            handle._set_value(new_index)
+        else:
+            handle._set_value(keyword)
+
+    def _get_float_value(self, handle: StyleValueHandle) -> float:
+        """Extract a float value from the handle."""
+        if handle.isValueIndexed():
+            int_value = self._buffer.get32(handle._value())
+            return struct.unpack("<f", struct.pack("<I", int_value))[0]
+        else:
+            return self._unpack_inline_integer(handle._value())
+
+    @staticmethod
+    def _is_integer_packable(f: float) -> bool:
+        """Check if a float can be packed as an inline integer."""
+        k_max_inline_abs_value = (1 << 11) - 1  # 2047
+        i = int(f)
+        return float(i) == f and -k_max_inline_abs_value <= i <= k_max_inline_abs_value
+
+    @staticmethod
+    def _pack_inline_integer(value: float) -> int:
+        """Pack a float as an inline integer."""
+        is_negative = 1 if value < 0 else 0
+        magnitude = abs(int(value))
+        return (is_negative << 11) | magnitude
+
+    @staticmethod
+    def _unpack_inline_integer(value: int) -> float:
+        """Unpack an inline integer to a float."""
+        k_value_sign_mask = 0b0000_1000_0000_0000
+        k_value_magnitude_mask = 0b0000_0111_1111_1111
+
+        is_negative = (value & k_value_sign_mask) != 0
+        magnitude = value & k_value_magnitude_mask
+        return float(-magnitude if is_negative else magnitude)
+
+    def copy(self) -> "StyleValuePool":
+        """Create a copy of this pool."""
+        new_pool = StyleValuePool()
+        new_pool._buffer = self._buffer.copy()
+        return new_pool

yoga/style/__init__.py

@@ -0,0 +1,16 @@
+"""
+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.
+"""
+
+from .GridLine import *
+from .GridTrack import *
+from .SmallValueBuffer import *
+from .Style import *
+from .StyleLength import *
+from .StyleSizeLength import *
+from .StyleValueHandle import *
+from .StyleValuePool import *
+

yoga_layout_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: yoga-layout-python
+Version: 0.1.0
+Summary: Pure Python port of Meta Yoga layout engine
+Author: Meta Platforms, Inc. and affiliates.
+Maintainer: Quantmew Contributors
+License: MIT License
+        
+        Copyright (c) Facebook, Inc. and its affiliates.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/quantmew/yoga-layout-python
+Project-URL: Repository, https://github.com/quantmew/yoga-layout-python
+Project-URL: Documentation, https://yogalayout.dev/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Dynamic: license-file
+
+# yoga-layout-python
+
+`yoga-layout-python` is a pure Python port of Meta's Yoga layout engine.
+
+## Current Status
+
+- Public enums, value/config primitives, and the core layout algorithm are implemented in Python.
+- Internal module layout mirrors upstream `yoga/` so translation and parity work can stay file-for-file aligned.
+- Upstream test translations pass, and a Python-vs-C++ differential parity harness is available under `tools/`.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+For development:
+
+```bash
+pip install -e ".[dev]"
+```
+
+## API Shape
+
+The Python package keeps Yoga's public naming style:
+
+```python
+from yoga import *
+
+config = YGConfigNew()
+node = YGNodeNewWithConfig(config)
+YGNodeStyleSetWidth(node, 100)
+YGNodeStyleSetHeight(node, 50)
+YGNodeCalculateLayout(node, YGUndefined, YGUndefined, YGDirectionLTR)
+
+width = YGNodeLayoutGetWidth(node)
+height = YGNodeLayoutGetHeight(node)
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=yoga --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_smoke.py -v
+```
+
+## Differential Parity
+
+The repository includes a differential parity runner that compares Python layout
+results against the vendored upstream C++ Yoga engine on the same captured tree.
+
+```bash
+# Run the default parity suite
+python tools/run_differential_ci.py
+
+# Rebuild the C++ runner first
+python tools/run_differential_ci.py --force-rebuild
+
+# Increase the random batch size
+python tools/run_differential_ci.py --random-count 1000 --seed 20260317
+```
+
+On failure, the script writes a repro capture to
+`build/differential_failure_capture.json`.
+
+The lower-level harness remains available if you want the raw output format:
+
+```bash
+python tools/differential_test.py
+```
+
+## Project Structure
+
+```
+src/yoga/
+├── algorithm/        # Core layout algorithms (CalculateLayout, FlexLine, etc.)
+├── config/           # Configuration handling
+├── debug/            # Debug utilities (logging, assertions)
+├── event/            # Event system
+├── node/             # Node class and layout results
+├── numeric/          # Numeric utilities (FloatOptional, Comparison)
+├── style/            # Style system (Style, StyleLength, etc.)
+└── *.py              # Public API modules
+
+tools/
+├── differential_cpp_runner.cpp  # C++ capture runner used for parity checks
+├── differential_test.py         # Python/C++ differential harness
+└── run_differential_ci.py       # Stable CLI entrypoint for parity checks
+```
+
+## License
+
+This project uses the same MIT license as upstream Yoga. See `LICENSE`.
+
+## Contributing
+
+Contributions are welcome! Please see the upstream [Yoga repository](https://github.com/facebook/yoga) for reference.