resforge 0.2.0__tar.gz → 0.3.1__tar.gz

{resforge-0.2.0 → resforge-0.3.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: resforge
-Version: 0.2.0
+Version: 0.3.1
 Summary: A type-safe Python DSL for cross-platform mobile resource generation
 Project-URL: Homepage, https://kipila.dev
-Project-URL: Repository, https://github.com/ok100/resforge
+Project-URL: Repository, https://github.com/kipila-dev/resforge
 Author-email: Ondrej Kipila <ondrej@kipila.dev>
 License: MIT
 License-File: LICENSE
@@ -17,13 +17,21 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Build Tools
 Requires-Python: >=3.12
 Provides-Extra: dev
+Requires-Dist: defusedxml; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # resforge
 
-A type-safe Python DSL for generating Android XML resources and Xcode Asset
-Catalogs (`.xcassets`).
+A type-safe Python DSL for generating native Android and iOS resources from design tokens.
+
+## Features
+
+- Fluent, Pythonic API
+- Jetpack Compose theme generation with type-safe color and dimension properties
+- Supports all Android `res/values/` types
+- Native Apple Asset Catalog (`.xcassets`) with dark mode support
+- Built-in validation for resource names and color formats
 
 ## Installation
 
@@ -33,7 +41,33 @@ pip install resforge
 
 ## Quick Example
 
-### Android
+### Android (Jetpack Compose)
+
+```python
+from resforge.android import ComposeWriter, dp
+
+with ComposeWriter("Theme.kt", "dev.kipila.example") as compose:
+    compose.dimension(border=dp(8))
+    with compose.object_("AppColors") as colors:
+        colors.color(primary="#FF0000", background="#FFFFFF")
+```
+
+```kotlin
+package dev.kipila.example
+
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+val border: Dp = 8.dp
+
+object AppColors {
+    val primary: Color = Color(0xFFFF0000)
+    val background: Color = Color(0xFFFFFFFF)
+}
+```
+
+### Android (XML Resources)
 
 ```python
 from resforge.android import ValuesWriter, dp, sp
@@ -123,83 +157,10 @@ with AssetCatalog("App", "Assets") as ac:
 }
 ```
 
-## Features
-
-- Fluent, Pythonic API
-- Supports all Android `res/values/` types
-- Built-in validation for Asset Catalog logic
-
-## Full Android Example
-
-```python
-from resforge.android import PluralValues, ValuesWriter, dp, sp
-
-with ValuesWriter("res/values/resources.xml") as res:
-    res.comment("Strings")
-    res.string(
-        app_name="My App",
-        welcome_message="Welcome to My App!",
-    )
-
-    res.comment("Booleans")
-    res.boolean(
-        feature_enabled=True,
-        dark_mode=False,
-    )
-
-    res.comment("Colors")
-    res.color(
-        primary="#FF6200EE",
-        secondary="#FF03DAC5",
-        accent="#6200EE",
-    )
-
-    res.comment("Dimensions")
-    res.dimension(
-        padding_small=dp(8),
-        padding_large=dp(24),
-        text_body=sp(16),
-        text_heading=sp(24),
-    )
-
-    res.comment("Integers")
-    res.integer(
-        max_retries=3,
-        timeout_seconds=30,
-    )
-
-    res.comment("Resource IDs")
-    res.res_id("btn_submit", "tv_title", "iv_logo")
-
-    res.comment("String arrays")
-    res.string_array("planets", ["Mercury", "Venus", "Earth", "Mars"])
-
-    res.comment("Integer arrays")
-    res.integer_array("fibonacci", [1, 1, 2, 3, 5, 8, 13])
-
-    res.comment("Typed arrays")
-    res.typed_array(
-        "icons", ["@drawable/home", "@drawable/settings", "@drawable/logout"]
-    )
-
-    res.comment("Plurals")
-    res.plurals(
-        item_count=PluralValues(one="%d item", other="%d items"),
-        file_count=PluralValues(one="%d file", other="%d files"),
-    )
-
-    res.comment("Styles")
-    res.style(
-        "AppTheme",
-        parent="Theme.MaterialComponents.DayNight",
-        colorPrimary="@color/primary",
-        colorSecondary="@color/secondary",
-    )
-```
-
 ## Roadmap
 
-- Support for more Asset Catalog types (ImageSet, IconSet)
+- Asset Catalog image support (ImageSet, IconSet)
+- Android `res/drawable` vector asset support
 
 ## License
 

{resforge-0.2.0 → resforge-0.3.1}/README.md

@@ -1,7 +1,14 @@
 # resforge
 
-A type-safe Python DSL for generating Android XML resources and Xcode Asset
-Catalogs (`.xcassets`).
+A type-safe Python DSL for generating native Android and iOS resources from design tokens.
+
+## Features
+
+- Fluent, Pythonic API
+- Jetpack Compose theme generation with type-safe color and dimension properties
+- Supports all Android `res/values/` types
+- Native Apple Asset Catalog (`.xcassets`) with dark mode support
+- Built-in validation for resource names and color formats
 
 ## Installation
 
@@ -11,7 +18,33 @@ pip install resforge
 
 ## Quick Example
 
-### Android
+### Android (Jetpack Compose)
+
+```python
+from resforge.android import ComposeWriter, dp
+
+with ComposeWriter("Theme.kt", "dev.kipila.example") as compose:
+    compose.dimension(border=dp(8))
+    with compose.object_("AppColors") as colors:
+        colors.color(primary="#FF0000", background="#FFFFFF")
+```
+
+```kotlin
+package dev.kipila.example
+
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+val border: Dp = 8.dp
+
+object AppColors {
+    val primary: Color = Color(0xFFFF0000)
+    val background: Color = Color(0xFFFFFFFF)
+}
+```
+
+### Android (XML Resources)
 
 ```python
 from resforge.android import ValuesWriter, dp, sp
@@ -101,83 +134,10 @@ with AssetCatalog("App", "Assets") as ac:
 }
 ```
 
-## Features
-
-- Fluent, Pythonic API
-- Supports all Android `res/values/` types
-- Built-in validation for Asset Catalog logic
-
-## Full Android Example
-
-```python
-from resforge.android import PluralValues, ValuesWriter, dp, sp
-
-with ValuesWriter("res/values/resources.xml") as res:
-    res.comment("Strings")
-    res.string(
-        app_name="My App",
-        welcome_message="Welcome to My App!",
-    )
-
-    res.comment("Booleans")
-    res.boolean(
-        feature_enabled=True,
-        dark_mode=False,
-    )
-
-    res.comment("Colors")
-    res.color(
-        primary="#FF6200EE",
-        secondary="#FF03DAC5",
-        accent="#6200EE",
-    )
-
-    res.comment("Dimensions")
-    res.dimension(
-        padding_small=dp(8),
-        padding_large=dp(24),
-        text_body=sp(16),
-        text_heading=sp(24),
-    )
-
-    res.comment("Integers")
-    res.integer(
-        max_retries=3,
-        timeout_seconds=30,
-    )
-
-    res.comment("Resource IDs")
-    res.res_id("btn_submit", "tv_title", "iv_logo")
-
-    res.comment("String arrays")
-    res.string_array("planets", ["Mercury", "Venus", "Earth", "Mars"])
-
-    res.comment("Integer arrays")
-    res.integer_array("fibonacci", [1, 1, 2, 3, 5, 8, 13])
-
-    res.comment("Typed arrays")
-    res.typed_array(
-        "icons", ["@drawable/home", "@drawable/settings", "@drawable/logout"]
-    )
-
-    res.comment("Plurals")
-    res.plurals(
-        item_count=PluralValues(one="%d item", other="%d items"),
-        file_count=PluralValues(one="%d file", other="%d files"),
-    )
-
-    res.comment("Styles")
-    res.style(
-        "AppTheme",
-        parent="Theme.MaterialComponents.DayNight",
-        colorPrimary="@color/primary",
-        colorSecondary="@color/secondary",
-    )
-```
-
 ## Roadmap
 
-- Support for more Asset Catalog types (ImageSet, IconSet)
+- Asset Catalog image support (ImageSet, IconSet)
+- Android `res/drawable` vector asset support
 
 ## License
 

{resforge-0.2.0 → resforge-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "resforge"
-version = "0.2.0"
+version = "0.3.1"
 description = "A type-safe Python DSL for cross-platform mobile resource generation"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -32,8 +32,58 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest"]
+dev = ["pytest", "defusedxml"]
 
 [project.urls]
 Homepage = "https://kipila.dev"
-Repository = "https://github.com/ok100/resforge"
+Repository = "https://github.com/kipila-dev/resforge"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "ANN001",
+  "ANN002",
+  "ANN003",
+  "COM812",
+  "COM819",
+  "D100",
+  "D102",
+  "D104",
+  "D105",
+  "D107",
+  "D206",
+  "D300",
+  "D401",
+  "E111",
+  "E114",
+  "E117",
+  "FIX",
+  "I001",
+  "PLR2004",
+  "Q000",
+  "Q001",
+  "Q002",
+  "Q003",
+  "TD",
+  "W191",
+]
+fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+   "ANN201",
+   "D101",
+   "D103",
+   "EM101",
+   "S101",
+   "TRY301",
+]
+
+[tool.basedpyright]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "standard"

resforge-0.3.1/resforge/_utils.py

@@ -0,0 +1,62 @@
+import os
+from collections.abc import Callable, Generator
+from contextlib import contextmanager, suppress
+from functools import wraps
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import IO, Concatenate
+
+
+def require_context[T, **P, R](
+    func: Callable[Concatenate[T, P], R],
+) -> Callable[Concatenate[T, P], R]:
+    """Ensures a method is only called within an active context.
+
+    Raises:
+        RuntimeError: If the method is called while the instance's
+            `_active` attribute is False or missing.
+
+    """
+
+    @wraps(func)
+    def wrapper(self: T, *args: P.args, **kwargs: P.kwargs) -> R:
+        if not getattr(self, "_active", False):
+            msg = f"'{func.__name__}' requires an active 'with' context."
+            raise RuntimeError(msg)
+        return func(self, *args, **kwargs)
+
+    return wrapper
+
+
+@contextmanager
+def atomic_write(target_path: Path) -> Generator[IO[bytes], None, None]:
+    """Yields a temporary file, then atomically replaces target_path on success."""
+    target_path = Path(target_path)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+
+    temp_path = None
+    try:
+        with NamedTemporaryFile(
+            dir=target_path.parent, delete=False, suffix=".tmp"
+        ) as tf:
+            temp_path = Path(tf.name)
+            yield tf
+
+            tf.flush()
+            os.fsync(tf.fileno())
+
+        temp_path.replace(target_path)
+
+        if os.name == "posix":
+            flags = os.O_RDONLY
+            if hasattr(os, "O_DIRECTORY"):
+                flags |= os.O_DIRECTORY
+            dir_fd = os.open(target_path.parent, flags)
+            try:
+                os.fsync(dir_fd)
+            finally:
+                os.close(dir_fd)
+    finally:
+        if temp_path and temp_path.exists():
+            with suppress(OSError):
+                temp_path.unlink()

{resforge-0.2.0 → resforge-0.3.1}/resforge/android/__init__.py

@@ -1,15 +1,16 @@
-from .dimension import Dimension, dp, inch, mm, pt, px, sp
-from .plural import PluralValues
+from .compose import ComposeWriter
+from .types import Dimension, PluralValues, dp, inch, mm, pt, px, sp
 from .values import ValuesWriter
 
 __all__ = [
+    "ComposeWriter",
     "Dimension",
+    "PluralValues",
+    "ValuesWriter",
     "dp",
     "inch",
     "mm",
     "pt",
     "px",
     "sp",
-    "PluralValues",
-    "ValuesWriter",
 ]

resforge-0.3.1/resforge/android/compose.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Self
+
+from resforge._utils import atomic_write, require_context
+from resforge.codegen.kotlin import KotlinFile, KotlinObject
+from resforge.types import Color
+
+if TYPE_CHECKING:
+    from resforge.android.types import Dimension
+
+__all__ = ["ComposeWriter"]
+
+
+class _ComposeContext:
+    def __init__(self, file: KotlinFile) -> None:
+        self._file = file
+
+    def add_imports(self, *fqns: str) -> None:
+        for fqn in fqns:
+            self._file.import_(fqn)
+
+
+class _BaseComposeScope:
+    def __init__(self, ctx: _ComposeContext, target: KotlinFile | KotlinObject) -> None:
+        self._ctx = ctx
+        self._target = target
+
+    @staticmethod
+    def _to_compose_color_literal(color: Color) -> str:
+        return f"Color({color.hex.replace('#', '0x')})"
+
+    @staticmethod
+    def _to_compose_dimen_literal(dimen: Dimension) -> str:
+        return f"{dimen.value}.{dimen.unit}"
+
+    @require_context
+    def color(self, **values: str | Color) -> Self:
+        """Appends one or more Color properties to the Kotlin object."""
+        if values:
+            self._ctx.add_imports("androidx.compose.ui.graphics.Color")
+        for name, color in values.items():
+            resolved = Color(color)
+            self._target.property(
+                name=name,
+                type_="Color",
+                value=self._to_compose_color_literal(resolved),
+            )
+        return self
+
+    @require_context
+    def dimension(self, **values: Dimension) -> Self:
+        """Appends one or more Dimension properties to the Kotlin object. Supports dp, sp and em.
+
+        Raises:
+            ValueError: If an unsupported unit (not dp, sp, or em) is provided.
+
+        """
+        mapping = {"dp": "Dp", "sp": "Sp", "em": "TextUnit"}
+        for name, dimen in values.items():
+            if dimen.unit not in mapping:
+                msg = f"Unsupported dimension type. Only dp, sp and em are supported (got {dimen.unit})."
+                raise ValueError(msg)
+            self._ctx.add_imports(
+                f"androidx.compose.ui.unit.{dimen.unit}",
+                f"androidx.compose.ui.unit.{mapping[dimen.unit]}",
+            )
+            self._target.property(
+                name=name,
+                type_=mapping[dimen.unit],
+                value=self._to_compose_dimen_literal(dimen),
+            )
+
+        return self
+
+
+class _ObjectScope(_BaseComposeScope):
+    def __enter__(self) -> Self:
+        self._active = True
+        return self
+
+    def __exit__(self, *_) -> None:
+        self._active = False
+
+
+class ComposeWriter(_BaseComposeScope):
+    """A fluent context manager for generating Jetpack Compose color definitions.
+
+    Writes a Kotlin file containing typed Color or Dimension properties.
+
+    Example:
+        >>> with ComposeWriter("ui/theme/Color.kt", package="com.example.theme", object_name="AppColors") as compose:
+        ...     compose.color(primary="#6200EE", background="#FFFFFF")
+
+    """
+
+    def __init__(self, path: str | Path, package: str) -> None:
+        """Initializes the ComposeWriter.
+
+        Args:
+            path: The filesystem path where the Kotlin file will be saved.
+            package: The Kotlin package declaration.
+
+        """
+        self._path = Path(path)
+        self._package = package
+        self._active = False
+
+    def __enter__(self) -> Self:
+        self._active = True
+        self._kotlin_file = KotlinFile(package=self._package)
+
+        ctx = _ComposeContext(self._kotlin_file)
+        super().__init__(ctx, self._kotlin_file)
+
+        return self
+
+    def __exit__(self, exc_type, *_) -> None:
+        try:
+            if exc_type is None:
+                with atomic_write(self._path) as tf:
+                    self._kotlin_file.write(tf)
+        finally:
+            self._active = False
+
+    @require_context
+    def object_(self, name: str) -> _ObjectScope:
+        """Creates a new Kotlin object within the file.
+
+        Args:
+            name: The name of the Kotlin object to generate.
+
+        Returns:
+            A new context tied to the generated object.
+
+        """
+        obj = KotlinObject(name=name)
+        self._kotlin_file.member(obj)
+        return _ObjectScope(self._ctx, obj)

resforge-0.3.1/resforge/android/types.py

@@ -0,0 +1,75 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal, NotRequired, TypedDict
+
+DimensionUnit = Literal["dp", "sp", "px", "pt", "mm", "in", "em"]
+
+
+@dataclass(frozen=True)
+class Dimension:
+    """Represents an Android dimension value (e.g., '16dp', '12sp').
+
+    Args:
+        value: The numeric dimension value. Negative values are permitted
+            to support negative margins/offsets, though they are
+            typically ignored by padding and size attributes.
+        unit: The unit of measure (dp, sp, px, pt, mm, in, em).
+
+    """
+
+    value: int | float
+    unit: DimensionUnit
+
+    def __str__(self) -> str:
+        return f"{self.value:g}{self.unit}"
+
+    def __repr__(self) -> str:
+        return f"Dimension(value={self.value!r}, unit={self.unit!r})"
+
+    def __mul__(self, other: float) -> "Dimension":
+        return Dimension(self.value * other, self.unit)
+
+    __rmul__ = __mul__
+
+
+def _make_unit_func(
+    unit: DimensionUnit, doc: str
+) -> Callable[[int | float], Dimension]:
+    def f(value: float) -> Dimension:
+        return Dimension(value, unit)
+
+    f.__name__ = unit
+    f.__doc__ = doc
+    return f
+
+
+dp = _make_unit_func("dp", "Create a dimension in density-independent pixels (dp).")
+sp = _make_unit_func(
+    "sp", "Create a dimension in scale-independent pixels (sp). Use for text sizes."
+)
+px = _make_unit_func("px", "Create a dimension in pixels (px).")
+pt = _make_unit_func("pt", "Create a dimension in points (pt).")
+mm = _make_unit_func("mm", "Create a dimension in millimeters (mm).")
+inch = _make_unit_func("in", "Create a dimension in inches (in).")
+em = _make_unit_func("em", "Create a dimension using a relative font size (em).")
+
+
+class PluralValues(TypedDict):
+    """Represents the quantity-based strings for an Android plurals resource.
+
+    Attributes:
+        zero: String for quantity 0 (optional).
+        one: String for quantity 1 (optional).
+        two: String for quantity 2 (optional).
+        few: String for quantity 'few' (optional).
+        many: String for quantity 'many' (optional).
+        other: The default fallback string (required).
+
+    """
+
+    zero: NotRequired[str]
+    one: NotRequired[str]
+    two: NotRequired[str]
+    few: NotRequired[str]
+    many: NotRequired[str]
+    other: str