qmk-skim 0.4.1__tar.gz

qmk_skim-0.4.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.3
+Name: qmk-skim
+Version: 0.4.1
+Summary: Svalboard Keymap Image Maker
+Keywords: svalboard,keyboard,keymap,layout,image,svg,png,typst
+Author: Thiago Alves
+Author-email: Thiago Alves <thiago@rapinialves.com>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Utilities
+Requires-Dist: click>=8.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typst>=0.12.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Svalboard Keymap Image Maker (skim)
+
+[![Coverage](https://img.shields.io/badge/coverage-96%25-brightgreen.svg)](https://github.com/Townk/skim)
+[![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/)
+[![Build Status](https://github.com/Townk/skim/actions/workflows/prerelease.yml/badge.svg)](https://github.com/Townk/skim/actions/workflows/prerelease.yml)
+[![PyPI version](https://badge.fury.io/py/qmk-skim.svg)](https://badge.fury.io/py/qmk-skim)
+
+A Python CLI tool for generating keymap layout images for the [Svalboard](https://svalboard.com) keyboard.
+
+## Features
+
+- Generate individual layer keymap images
+- Generate overview images showing all layers
+- Support for multiple keymap formats:
+  - Keybard (`.kbi`)
+  - Vial (`.vil`)
+  - QMK c2json (`.json`)
+- Configurable colors and appearance
+- High-quality SVG and PNG output
+
+## Installation
+
+```bash
+pip install skim
+```
+
+## Usage
+
+### Generate keymap images
+
+```bash
+# Generate from a keymap file
+skim generate --keymap my-keymap.kbi --output-dir ./images
+
+# Generate with custom configuration
+skim generate --keymap my-keymap.kbi --config skim-config.yaml --output-dir ./images
+
+# Generate specific layers only
+skim generate --keymap my-keymap.kbi --layer 1 --layer 3-5 --layer overview
+```
+
+### Configuration helper
+
+```bash
+# Create a configuration file from QMK color.h
+skim configure --qmk-color-header /path/to/qmk/quantum/color.h --output skim-config.yaml
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/skim.git
+cd skim
+
+# Create virtual environment and install dependencies
+uv venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+uv sync --dev
+```
+
+### Testing
+
+```bash
+# Run tests with coverage
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/unit/domain/test_colors.py
+```
+
+### Building Documentation
+
+```bash
+cd docs
+sphinx-build -b html . _build
+```
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

qmk_skim-0.4.1/README.md

@@ -0,0 +1,87 @@
+# Svalboard Keymap Image Maker (skim)
+
+[![Coverage](https://img.shields.io/badge/coverage-96%25-brightgreen.svg)](https://github.com/Townk/skim)
+[![Python Version](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/)
+[![Build Status](https://github.com/Townk/skim/actions/workflows/prerelease.yml/badge.svg)](https://github.com/Townk/skim/actions/workflows/prerelease.yml)
+[![PyPI version](https://badge.fury.io/py/qmk-skim.svg)](https://badge.fury.io/py/qmk-skim)
+
+A Python CLI tool for generating keymap layout images for the [Svalboard](https://svalboard.com) keyboard.
+
+## Features
+
+- Generate individual layer keymap images
+- Generate overview images showing all layers
+- Support for multiple keymap formats:
+  - Keybard (`.kbi`)
+  - Vial (`.vil`)
+  - QMK c2json (`.json`)
+- Configurable colors and appearance
+- High-quality SVG and PNG output
+
+## Installation
+
+```bash
+pip install skim
+```
+
+## Usage
+
+### Generate keymap images
+
+```bash
+# Generate from a keymap file
+skim generate --keymap my-keymap.kbi --output-dir ./images
+
+# Generate with custom configuration
+skim generate --keymap my-keymap.kbi --config skim-config.yaml --output-dir ./images
+
+# Generate specific layers only
+skim generate --keymap my-keymap.kbi --layer 1 --layer 3-5 --layer overview
+```
+
+### Configuration helper
+
+```bash
+# Create a configuration file from QMK color.h
+skim configure --qmk-color-header /path/to/qmk/quantum/color.h --output skim-config.yaml
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-repo/skim.git
+cd skim
+
+# Create virtual environment and install dependencies
+uv venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+uv sync --dev
+```
+
+### Testing
+
+```bash
+# Run tests with coverage
+uv run pytest
+
+# Run specific test file
+uv run pytest tests/unit/domain/test_colors.py
+```
+
+### Building Documentation
+
+```bash
+cd docs
+sphinx-build -b html . _build
+```
+
+## License
+
+MIT License
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

qmk_skim-0.4.1/pyproject.toml

@@ -0,0 +1,121 @@
+[project]
+name = "qmk-skim"
+version = "0.4.1"
+description = "Svalboard Keymap Image Maker"
+readme = "README.md"
+authors = [
+    { name = "Thiago Alves", email = "thiago@rapinialves.com" }
+]
+keywords = ["svalboard", "keyboard", "keymap", "layout", "image", "svg", "png", "typst"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Utilities",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.1.0",
+    "pyyaml>=6.0",
+    "typst>=0.12.0",
+]
+
+[project.scripts]
+skim = "skim.ui.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "--cov=skim --cov-report=html --cov-report=term-missing"
+minversion = "8.0"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/__pycache__/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if __name__ == .__main__.:",
+    "raise AssertionError",
+    "raise NotImplementedError",
+]
+fail_under = 95
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+    "C901",   # too complex
+    "ARG001", # unused function argument
+    "ARG002", # unused method argument
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["skim"]
+force-single-line = false
+combine-as-imports = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = true
+
+[tool.basedpyright]
+pythonVersion = "3.10"
+typeCheckingMode = "standard"
+include = ["src"]
+exclude = ["**/node_modules", "**/__pycache__", ".git", "build", "dist"]
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = true
+reportUnusedVariable = true
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "skim"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.8.0",
+    "basedpyright>=1.22.0",
+]
+docs = [
+    "sphinx>=8.1.3",
+    "furo>=2024.0.0",
+    "sphinx-autodoc-typehints>=2.0.0",
+    "myst-parser>=3.0.0",
+]

qmk_skim-0.4.1/src/skim/__init__.py

@@ -0,0 +1,40 @@
+"""Skim - Svalboard Keymap Image Maker.
+
+A command-line tool for generating visual keyboard layout images from QMK,
+Vial, and Keybard keymap files. Skim parses keymap definitions and produces
+high-quality SVG or PNG images suitable for documentation, reference cards,
+or sharing keyboard layouts.
+
+Example:
+    Generate images from a keymap file::
+
+        $ skim generate --keymap my-layout.kbi --output-dir ./images
+
+    Generate with custom configuration::
+
+        $ skim generate -k layout.vil -c config.yaml -o ./out -f png
+
+    Create a configuration from a Keybard file::
+
+        $ skim configure -k my-layout.kbi -o skim-config.yaml
+"""
+
+from importlib.metadata import metadata
+
+_metadata = metadata("qmk-skim")
+__version__ = _metadata["Version"]
+__prog_name__ = f"{_metadata['Summary']} ({_metadata['Name']})"
+
+
+def main() -> None:
+    """Entry point placeholder for the skim package.
+
+    This function serves as a simple entry point for package verification.
+    The actual CLI functionality is provided by the :mod:`skim.ui.cli` module
+    through Click commands.
+
+    Note:
+        For CLI usage, invoke ``skim`` directly or use
+        ``python -m skim.ui.cli``.
+    """
+    print("Hello from skim!")

qmk_skim-0.4.1/src/skim/application/config_generator.py

@@ -0,0 +1,159 @@
+"""Configuration Generator for creating Skim config from source files.
+
+This module provides the :class:`ConfigGenerator` which extracts metadata
+from Keybard keymap files and QMK color headers to generate Skim YAML
+configuration files. This automates the initial configuration setup
+for users migrating from these tools.
+
+The generator extracts:
+    - Layer colors (converted from HSV to hex)
+    - Layer names from cosmetic settings
+    - Custom keycode short names for display labels
+    - Named color definitions from QMK headers
+
+Example:
+    Generating configuration from a Keybard file::
+
+        generator = ConfigGenerator()
+        yaml_config = generator.generate(
+            keybard_content=keybard_json_str,
+            qmk_header_content=qmk_color_h_content,
+            adjust_lightness=0.31,
+        )
+        Path("skim-config.yaml").write_text(yaml_config)
+"""
+
+import colorsys
+import re
+
+import yaml
+
+from skim.application.parsers.keybard_parser import KeybardParser
+from skim.application.parsers.qmk_color_parser import QmkColorParser
+from skim.domain.colors import adjust_color, hex_str
+
+
+class ConfigGenerator:
+    """Generates Skim configuration YAML from source keymap files.
+
+    This class extracts relevant metadata from Keybard (.kbi) files and
+    optional QMK color headers to produce a ready-to-use Skim configuration.
+    The generated config includes layer definitions, color schemes, and
+    keycode display overrides.
+
+    Example:
+        >>> generator = ConfigGenerator()
+        >>> yaml_output = generator.generate(keybard_content)
+        >>> print(yaml_output)
+        layers:
+          - base_color: '#347156'
+            label: BASE
+            name: Base
+            id: '0'
+        ...
+    """
+
+    def generate(
+        self,
+        keybard_content: str,
+        qmk_header_content: str | None = None,
+        adjust_lightness: float | None = None,
+        adjust_saturation: float | None = None,
+    ) -> str:
+        """Generate YAML configuration from Keybard content.
+
+        Parses the Keybard JSON file to extract layer colors, names, and
+        custom keycode definitions. Optionally integrates QMK color
+        definitions from a color.h header file.
+
+        Args:
+            keybard_content: JSON string content of the Keybard .kbi file.
+            qmk_header_content: Optional C header content from QMK color.h
+                file containing RGB_* and HSV_* color definitions.
+            adjust_lightness: Optional target lightness (0.0-1.0) to apply
+                to all extracted colors. Useful for ensuring readable
+                contrast in generated images.
+            adjust_saturation: Optional maximum saturation (0.0-1.0) to cap
+                all extracted colors. Original saturation is reduced to
+                this value if it exceeds the target.
+
+        Returns:
+            YAML-formatted string containing the generated Skim configuration.
+            Ready to be written to a .yaml file.
+
+        Raises:
+            ValueError: If keybard_content contains invalid JSON.
+
+        Example:
+            >>> generator = ConfigGenerator()
+            >>> config = generator.generate(
+            ...     keybard_content=Path("layout.kbi").read_text(),
+            ...     qmk_header_content=Path("color.h").read_text(),
+            ...     adjust_lightness=0.31,
+            ... )
+            >>> Path("skim-config.yaml").write_text(config)
+        """
+        parser = KeybardParser()
+        metadata = parser.extract_metadata(keybard_content)
+
+        def apply_adjustment(hex_c: str) -> str:
+            if adjust_lightness is not None or adjust_saturation is not None:
+                return adjust_color(hex_c, adjust_lightness, adjust_saturation)
+            return hex_c
+
+        qmk_colors = {}
+        if qmk_header_content:
+            qmk_parser = QmkColorParser()
+            qmk_colors = qmk_parser.parse(qmk_header_content)
+            for k, v in qmk_colors.items():
+                qmk_colors[k] = apply_adjustment(v)
+
+        layers_config = []
+        layer_colors = metadata.get("layer_colors", [])
+        layer_names = metadata.get("layer_names", {})
+
+        for idx, color_data in enumerate(layer_colors):
+            h = color_data.get("hue", 0) / 255.0
+            s = color_data.get("sat", 255) / 255.0
+            v = color_data.get("val", 255) / 255.0
+
+            r, g, b = colorsys.hsv_to_rgb(h, s, v)
+            base_color = hex_str(r, g, b)
+            base_color = apply_adjustment(base_color)
+
+            idx_str = str(idx)
+            name = layer_names.get(idx_str, f"Layer {idx}")
+
+            layer_entry = {
+                "base_color": base_color,
+                "label": name.upper()[:4].strip(),
+                "name": name,
+                "id": str(idx),
+            }
+            layers_config.append(layer_entry)
+
+        overrides = {}
+        for item in metadata.get("custom_keycodes", []):
+            if "name" in item and "shortName" in item:
+                short_name = item["shortName"]
+                short_name = re.sub(r"\s+", " ", short_name).strip()
+                overrides[item["name"]] = short_name
+
+        config_dict = {
+            "layers": layers_config,
+            "appearance": {
+                "colors": {
+                    "text": "#000000",
+                    "background": "#FFFFFF",
+                    "neutral": "#70768B",
+                }
+            },
+        }
+
+        if qmk_colors:
+            config_dict["appearance"]["colors"]["named_colors"] = qmk_colors
+
+        if overrides:
+            config_dict["keycodes"] = overrides
+
+        return yaml.dump(config_dict, sort_keys=False)