xllify 0.8.9__py3-none-any.whl

xllify/funcinfo.py

@@ -0,0 +1,375 @@
+#!/usr/bin/env python3
+"""
+Python Function Info Extractor for xllify
+
+Parses Python files to extract metadata from @xllify.fn() decorated functions
+and outputs structured JSON similar to the Luau funcinfo tool.
+
+Usage:
+    xllify-funcinfo <script.py>
+    python -m xllify.funcinfo <script.py>
+
+Output:
+    JSON object containing:
+    - script_name: Name of the script
+    - functions: Array of function metadata
+"""
+
+import ast
+import json
+import sys
+import os
+from typing import List, Dict, Any, Optional
+from pathlib import Path
+
+
+class ParameterInfo:
+    """Information about a function parameter"""
+
+    def __init__(
+        self,
+        name: str,
+        type_hint: str = "any",
+        optional: bool = False,
+        default: Any = None,
+        description: str = "",
+    ):
+        self.name = name
+        self.type_hint = type_hint
+        self.optional = optional
+        self.default = default
+        self.description = description
+
+    def to_dict(self) -> dict:
+        result = {"name": self.name, "type": self.type_hint, "optional": self.optional}
+        if self.default is not None:
+            result["default"] = self.default
+        if self.description:
+            result["description"] = self.description
+        return result
+
+
+class FunctionMetadata:
+    """Metadata for an Excel function"""
+
+    def __init__(self):
+        self.config_name: str = ""
+        self.description: str = ""
+        self.category: str = ""
+        self.execution_type: str = "external"  # Python functions always use external execution
+        self.parameters: List[ParameterInfo] = []
+        self.has_vararg: bool = False
+        self.has_kwargs: bool = False
+        self.return_type: str = "any"
+
+    def to_dict(self) -> dict:
+        result = {
+            "config_name": self.config_name,
+            "description": self.description,
+            "category": self.category,
+            "execution_type": self.execution_type,
+            "parameters": [p.to_dict() for p in self.parameters],
+            "has_vararg": self.has_vararg,
+        }
+        if self.has_kwargs:
+            result["has_kwargs"] = self.has_kwargs
+        if self.return_type != "any":
+            result["return_type"] = self.return_type
+        return result
+
+
+class FunctionExtractor(ast.NodeVisitor):
+    """AST visitor to extract xllify.fn decorated functions"""
+
+    def __init__(self):
+        self.functions: List[FunctionMetadata] = []
+        self._current_decorators = []
+        self.spawn_count: Optional[int] = None
+
+    def visit_Expr(self, node: ast.Expr):
+        """Visit expression statements to find configure_spawn_count() calls"""
+        if isinstance(node.value, ast.Call):
+            self._check_spawn_count_call(node.value)
+        self.generic_visit(node)
+
+    def visit_FunctionDef(self, node: ast.FunctionDef):
+        """Visit function definitions and extract metadata if decorated with @xllify.fn"""
+        # Check if this function has an @xllify.fn decorator
+        xllify_decorator = self._find_xllify_decorator(node.decorator_list)
+
+        if xllify_decorator:
+            metadata = self._extract_metadata(node, xllify_decorator)
+            if metadata:
+                self.functions.append(metadata)
+
+        self.generic_visit(node)
+
+    def _check_spawn_count_call(self, call: ast.Call):
+        """Check if this is a configure_spawn_count() call and extract the value"""
+        # Check for xllify.configure_spawn_count(...)
+        if isinstance(call.func, ast.Attribute):
+            if (
+                call.func.attr == "configure_spawn_count"
+                and isinstance(call.func.value, ast.Name)
+                and call.func.value.id == "xllify"
+            ):
+                self._extract_spawn_count(call)
+        # Check for configure_spawn_count(...) where it was imported from xllify
+        elif isinstance(call.func, ast.Name):
+            if call.func.id == "configure_spawn_count":
+                self._extract_spawn_count(call)
+
+    def _extract_spawn_count(self, call: ast.Call):
+        """Extract the spawn_count value from the function call"""
+        if call.args and isinstance(call.args[0], ast.Constant):
+            if isinstance(call.args[0].value, int):
+                self.spawn_count = call.args[0].value
+
+    def _find_xllify_decorator(self, decorators: List[ast.expr]) -> Optional[ast.Call]:
+        """Find the @xllify.fn() or @fn() decorator call if present"""
+        for decorator in decorators:
+            if isinstance(decorator, ast.Call):
+                # Check if it's xllify.fn(...)
+                if isinstance(decorator.func, ast.Attribute):
+                    if (
+                        decorator.func.attr == "fn"
+                        and isinstance(decorator.func.value, ast.Name)
+                        and decorator.func.value.id == "xllify"
+                    ):
+                        return decorator
+                # Check if it's fn(...) where fn was imported from xllify
+                elif isinstance(decorator.func, ast.Name):
+                    if decorator.func.id == "fn":
+                        return decorator
+        return None
+
+    def _extract_metadata(
+        self, func_node: ast.FunctionDef, decorator: ast.Call
+    ) -> Optional[FunctionMetadata]:
+        """Extract all metadata from a decorated function"""
+        metadata = FunctionMetadata()
+
+        # Extract config from decorator arguments (this may set return_type)
+        decorator_params = self._extract_decorator_config(decorator, metadata)
+        decorator_return_type = metadata.return_type
+
+        # Extract function signature (this may override return_type from annotation)
+        self._extract_function_signature(func_node, metadata)
+        if decorator_return_type and decorator_return_type != "any":
+            metadata.return_type = decorator_return_type
+
+        if decorator_params:
+            self._merge_parameter_descriptions(metadata, decorator_params)
+
+        # Extract docstring as description only if not already set
+        if not metadata.description:
+            docstring = ast.get_docstring(func_node)
+            if docstring:
+                metadata.description = docstring.strip()
+
+        return metadata
+
+    def _extract_decorator_config(
+        self, decorator: ast.Call, metadata: FunctionMetadata
+    ) -> Optional[Dict[str, Dict]]:
+        """Extract configuration from @xllify.fn() decorator arguments
+
+        Returns:
+            Dictionary mapping parameter names to their metadata (description, type) if parameters kwarg exists
+        """
+        decorator_params = None
+
+        # First positional argument is the function name
+        if decorator.args:
+            name_arg = decorator.args[0]
+            if isinstance(name_arg, ast.Constant):
+                metadata.config_name = name_arg.value
+
+        # Check for keyword arguments: description, category, parameters, return_type
+        # Note: execution_type is always "external" for Python functions
+        for keyword in decorator.keywords:
+            if keyword.arg == "description" and isinstance(keyword.value, ast.Constant):
+                metadata.description = keyword.value.value
+            elif keyword.arg == "category" and isinstance(keyword.value, ast.Constant):
+                metadata.category = keyword.value.value
+            elif keyword.arg == "return_type" and isinstance(keyword.value, ast.Constant):
+                metadata.return_type = keyword.value.value
+            elif keyword.arg == "parameters" and isinstance(keyword.value, ast.List):
+                decorator_params = self._parse_parameters_list(keyword.value)
+
+        return decorator_params
+
+    def _parse_parameters_list(self, params_list: ast.List) -> Dict[str, Dict]:
+        """Parse the parameters list from decorator into a dict keyed by parameter name
+
+        Expects Parameter(name="...", type="...", description="...") objects
+        """
+        result = {}
+
+        for elem in params_list.elts:
+            if isinstance(elem, ast.Call):
+                if isinstance(elem.func, ast.Name) and elem.func.id == "Parameter":
+                    param_info = self._parse_parameter_call(elem)
+                    if param_info and "name" in param_info:
+                        result[param_info["name"]] = param_info
+
+        return result
+
+    def _parse_parameter_call(self, call: ast.Call) -> Dict[str, str]:
+        """Parse a Parameter(...) call into a dict"""
+        param_info = {}
+
+        # Handle positional argument (name)
+        if call.args and isinstance(call.args[0], ast.Constant):
+            param_info["name"] = call.args[0].value
+
+        # Handle keyword arguments
+        for keyword in call.keywords:
+            if isinstance(keyword.value, ast.Constant):
+                param_info[keyword.arg] = keyword.value.value
+
+        return param_info
+
+    def _merge_parameter_descriptions(
+        self, metadata: FunctionMetadata, decorator_params: Dict[str, Dict]
+    ):
+        """Merge parameter descriptions from decorator into extracted parameter info"""
+        for param in metadata.parameters:
+            if param.name in decorator_params:
+                decorator_info = decorator_params[param.name]
+                if "description" in decorator_info:
+                    param.description = decorator_info["description"]
+                if "type" in decorator_info and param.type_hint == "any":
+                    param.type_hint = decorator_info["type"]
+
+    def _extract_function_signature(self, func_node: ast.FunctionDef, metadata: FunctionMetadata):
+        """Extract parameter information from function signature"""
+        args = func_node.args
+
+        # Process regular arguments
+        num_defaults = len(args.defaults)
+        num_args = len(args.args)
+
+        for i, arg in enumerate(args.args):
+            if arg.arg == "self":  # Skip self parameter
+                continue
+
+            param = ParameterInfo(name=arg.arg)
+
+            # Extract type annotation
+            if arg.annotation:
+                param.type_hint = self._get_type_name(arg.annotation)
+
+            # Check if parameter has a default value (making it optional)
+            default_index = i - (num_args - num_defaults)
+            if default_index >= 0:
+                param.optional = True
+                default_value = args.defaults[default_index]
+                param.default = self._get_default_value(default_value)
+
+            metadata.parameters.append(param)
+
+        if args.vararg:
+            metadata.has_vararg = True
+
+        if args.kwarg:
+            metadata.has_kwargs = True
+
+        # Extract return type annotation
+        if func_node.returns:
+            metadata.return_type = self._get_type_name(func_node.returns)
+
+    def _get_type_name(self, annotation: ast.expr) -> str:
+        """Extract type name from type annotation"""
+        if isinstance(annotation, ast.Name):
+            return annotation.id
+        elif isinstance(annotation, ast.Constant):
+            return str(annotation.value)
+        elif isinstance(annotation, ast.Subscript):
+            # Handle types like List[str], Dict[str, int], Optional[str]
+            if isinstance(annotation.value, ast.Name):
+                base_type = annotation.value.id
+                if isinstance(annotation.slice, ast.Name):
+                    inner_type = annotation.slice.id
+                    return f"{base_type}[{inner_type}]"
+                elif isinstance(annotation.slice, ast.Tuple):
+                    inner_types = [self._get_type_name(elt) for elt in annotation.slice.elts]
+                    return f"{base_type}[{', '.join(inner_types)}]"
+                return base_type
+        elif isinstance(annotation, ast.Attribute):
+            # Handle types like typing.Optional
+            return annotation.attr
+
+        return "any"
+
+    def _get_default_value(self, node: ast.expr) -> Any:
+        """Extract default value from AST node"""
+        if isinstance(node, ast.Constant):
+            return node.value
+        elif isinstance(node, ast.Name):
+            if node.id == "None":
+                return None
+            elif node.id == "True":
+                return True
+            elif node.id == "False":
+                return False
+        elif isinstance(node, ast.List):
+            return []
+        elif isinstance(node, ast.Dict):
+            return {}
+
+        return None
+
+
+def extract_functions(source_code: str) -> tuple[List[FunctionMetadata], Optional[int]]:
+    """Parse Python source code and extract xllify function metadata
+
+    Returns:
+        Tuple of (functions list, spawn_count if configured)
+    """
+    try:
+        tree = ast.parse(source_code)
+        extractor = FunctionExtractor()
+        extractor.visit(tree)
+        return extractor.functions, extractor.spawn_count
+    except SyntaxError as e:
+        print(f"Syntax error in Python file: {e}", file=sys.stderr)
+        return [], None
+
+
+def output_json(script_name: str, functions: List[FunctionMetadata], spawn_count: Optional[int] = None) -> str:
+    """Generate JSON output from extracted function metadata"""
+    output = {"script_name": script_name, "functions": [func.to_dict() for func in functions]}
+    if spawn_count is not None:
+        output["spawn_count"] = spawn_count
+    return json.dumps(output, indent=2)
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(f"Usage: {sys.argv[0]} <script.py>", file=sys.stderr)
+        sys.exit(1)
+
+    filename = sys.argv[1]
+
+    # Extract script name from filename
+    script_name = Path(filename).stem
+
+    try:
+        with open(filename, "r", encoding="utf-8") as f:
+            source_code = f.read()
+    except FileNotFoundError:
+        print(f"Error: Could not open file {filename}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        print(f"Error reading file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    functions, spawn_count = extract_functions(source_code)
+    print(output_json(script_name, functions, spawn_count))
+    # yay
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

xllify/install.py

@@ -0,0 +1,251 @@
+"""
+xllify-install - Download and install the xllify CLI binary
+
+This module provides functionality to download and install the xllify CLI
+binary for Windows and macOS.
+"""
+
+import os
+import sys
+import platform
+import zipfile
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import requests
+
+
+def get_xllify_version() -> str:
+    """
+    Read the xllify CLI version from the XLLIFY_DIST_VERSION file.
+
+    Returns:
+        The version string (e.g., "0.7.6")
+    """
+    # Look for XLLIFY_DIST_VERSION file in the package directory
+    version_file = Path(__file__).parent / "XLLIFY_DIST_VERSION"
+
+    if not version_file.exists():
+        raise FileNotFoundError(
+            f"XLLIFY_DIST_VERSION file not found at {version_file}. "
+            "Please ensure the file exists in the package."
+        )
+
+    return version_file.read_text().strip()
+
+
+def get_download_urls(version: Optional[str] = None) -> dict:
+    """
+    Get the download URLs for the xllify binaries based on platform.
+
+    Args:
+        version: Specific version to download (defaults to version from XLLIFY_DIST_VERSION)
+
+    Returns:
+        Dictionary with 'dist' and 'cli' URLs for the current platform
+    """
+    if version is None:
+        version = get_xllify_version()
+
+    system = platform.system()
+    base_url = "https://storage.googleapis.com/xllify-action-assets"
+
+    if system == "Windows":
+        return {
+            "dist": f"{base_url}/xllify-dist-v{version}-windows.zip",
+            "cli": f"{base_url}/xllify-cli-v{version}-windows.zip",
+        }
+    elif system == "Darwin":  # macOS
+        return {"cli": f"{base_url}/xllify-cli-v{version}-macos.zip"}
+    else:
+        raise OSError(f"Unsupported platform: {system}. Only Windows and macOS are supported.")
+
+
+def get_bin_directory() -> Path:
+    """
+    Get the bin directory in the current virtual environment.
+
+    Returns:
+        Path to the bin/Scripts directory where executables should be installed.
+    """
+    # Check if we're in a virtual environment
+    venv_path = os.environ.get("VIRTUAL_ENV")
+
+    if venv_path:
+        base_path = Path(venv_path)
+    else:
+        base_path = Path(sys.prefix)
+
+    if platform.system() == "Windows":
+        bin_dir = base_path / "Scripts"
+    else:
+        bin_dir = base_path / "bin"
+
+    return bin_dir
+
+
+def download_file(url: str, dest_path: Path, progress: bool = True) -> None:
+    print(f"Downloading from {url}...")
+
+    response = requests.get(url, stream=True)
+    response.raise_for_status()  # Raise exception for HTTP errors
+
+    total_size = int(response.headers.get("content-length", 0))
+
+    with open(dest_path, "wb") as f:
+        if total_size and progress:
+            downloaded = 0
+            chunk_size = 8192
+
+            for chunk in response.iter_content(chunk_size=chunk_size):
+                if chunk:  # filter out keep-alive new chunks
+                    f.write(chunk)
+                    downloaded += len(chunk)
+
+                    # Show progress
+                    percent = (downloaded / total_size) * 100
+                    print(f"\rProgress: {percent:.1f}% ({downloaded}/{total_size} bytes)", end="")
+
+            print()  # New line after progress
+        else:
+            # No progress bar, just download
+            for chunk in response.iter_content(chunk_size=8192):
+                if chunk:
+                    f.write(chunk)
+
+    print(f"Downloaded to {dest_path}")
+
+
+def extract_zip(zip_path: Path, extract_dir: Path) -> None:
+    print(f"Extracting {zip_path.name}...")
+
+    with zipfile.ZipFile(zip_path, "r") as zip_ref:
+        zip_ref.extractall(extract_dir)
+
+    print(f"Extracted to {extract_dir}")
+
+
+def install_binaries_from_zip(zip_url: str, zip_name: str, bin_dir: Path, temp_dir: Path) -> None:
+    # Download the zip file
+    zip_path = temp_dir / zip_name
+    download_file(zip_url, zip_path)
+
+    # Extract the zip file to a subdirectory to avoid conflicts
+    extract_subdir = temp_dir / zip_name.replace(".zip", "")
+    extract_subdir.mkdir(exist_ok=True)
+    extract_zip(zip_path, extract_subdir)
+
+    # Find and move executable files to bin directory
+    # On Windows, look for .exe files; on macOS/Unix, look for files without extension or with execute permission
+    if platform.system() == "Windows":
+        executables = list(extract_subdir.glob("*.exe"))
+    else:
+        # On macOS/Unix, find executable files
+        executables = [f for f in extract_subdir.iterdir() if f.is_file() and os.access(f, os.X_OK)]
+
+    if not executables:
+        print(f"Warning: No executable files found in {zip_name}")
+        return
+
+    for exe_file in executables:
+        dest_path = bin_dir / exe_file.name
+
+        # Remove existing file if it exists
+        if dest_path.exists():
+            print(f"Removing existing {dest_path.name}...")
+            dest_path.unlink()
+
+        # Move the executable to bin directory
+        shutil.move(str(exe_file), str(dest_path))
+
+        # Ensure it's executable on Unix-like systems
+        if platform.system() != "Windows":
+            dest_path.chmod(0o755)
+
+        print(f"Installed {exe_file.name} to {dest_path}")
+
+
+def install_binary(version: Optional[str] = None, custom_urls: Optional[dict] = None) -> None:
+    if version is None:
+        version = get_xllify_version()
+
+    if custom_urls is None:
+        download_urls = get_download_urls(version)
+    else:
+        download_urls = custom_urls
+
+    # Get the bin directory
+    bin_dir = get_bin_directory()
+    bin_dir.mkdir(parents=True, exist_ok=True)
+
+    system = platform.system()
+    print(f"Installing xllify v{version} for {system} to {bin_dir}")
+
+    # Create a temporary directory for download
+    temp_dir = bin_dir / ".xllify-install-temp"
+    temp_dir.mkdir(exist_ok=True)
+
+    try:
+        # Install dist binary (Windows only)
+        if "dist" in download_urls:
+            print("\nInstalling xllify-dist...")
+            install_binaries_from_zip(download_urls["dist"], "xllify-dist.zip", bin_dir, temp_dir)
+
+        # Install CLI binary (all platforms)
+        if "cli" in download_urls:
+            print("\nInstalling xllify-cli...")
+            install_binaries_from_zip(download_urls["cli"], "xllify-cli.zip", bin_dir, temp_dir)
+
+        print("\nInstallation complete!")
+        print(f"\nThe xllify binaries are now available in your PATH at:")
+        print(f"  {bin_dir}")
+
+        # Check if bin directory is in PATH
+        path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+        if str(bin_dir) not in path_dirs:
+            print("\nWarning: The bin directory may not be in your PATH.")
+            print("If you're using a virtual environment, make sure it's activated.")
+
+    finally:
+        # Clean up temporary directory
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir)
+
+
+def main() -> None:
+    """Main entry point for the xllify-install command."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Download and install the xllify binaries for your platform"
+    )
+    parser.add_argument(
+        "--version",
+        help="Specific version to install (default: read from XLLIFY_DIST_VERSION)",
+        default=None,
+    )
+    parser.add_argument(
+        "--dist-url", help="Custom download URL for xllify-dist (Windows only)", default=None
+    )
+    parser.add_argument("--cli-url", help="Custom download URL for xllify-cli", default=None)
+
+    args = parser.parse_args()
+
+    try:
+        custom_urls = None
+        if args.dist_url or args.cli_url:
+            custom_urls = {}
+            if args.dist_url:
+                custom_urls["dist"] = args.dist_url
+            if args.cli_url:
+                custom_urls["cli"] = args.cli_url
+
+        install_binary(version=args.version, custom_urls=custom_urls)
+    except Exception as e:
+        print(f"\nError during installation: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

xllify/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 - indicates this package supports type hints