Skip to content

api_reference.md

Latest commit

 

History

History
405 lines (290 loc) · 8.84 KB

api_reference.md

File metadata and controls

405 lines (290 loc) · 8.84 KB
Raw

API Reference

This document provides detailed information about the Snakeskin API.

Component Class

The Component class is the core building block of Snakeskin applications.

Constructor

Component(**props)

Parameters:

  • props: A dictionary of properties passed to the component

Example:

from snakeskin.framework import Component

# Create a component with props
my_component = Component(title="Hello", subtitle="World")

Properties

Property Type Description
props dict Properties passed to the component
state dict Internal state of the component
_observers list List of observer callbacks
_mounted bool Whether the component is mounted
_lifecycle_hooks dict Dictionary of lifecycle hook callbacks

Methods

set_state(new_state: dict) -> str

Updates the component's state and triggers a re-render.

Parameters:

  • new_state: A dictionary of state values to update

Returns:

  • The rendered HTML as a string

Example:

component.set_state({"count": 42})

mount() -> str

Mounts the component and triggers the 'mounted' lifecycle hook.

Returns:

  • The rendered HTML as a string

Example:

html = component.mount()

unmount() -> None

Unmounts the component and triggers the 'before_unmount' lifecycle hook.

Example:

component.unmount()

observe(callback: callable) -> int

Adds an observer callback that will be called when the state changes.

Parameters:

  • callback: A function that takes the state as a parameter

Returns:

  • An observer ID that can be used to remove the observer

Example:

def log_state(state):
    print(f"State changed: {state}")

observer_id = component.observe(log_state)

unobserve(observer_id: int) -> None

Removes an observer callback.

Parameters:

  • observer_id: The ID returned by the observe method

Example:

component.unobserve(observer_id)

on(event: str, callback: callable) -> None

Registers a callback for a lifecycle event.

Parameters:

  • event: The name of the event ('before_mount', 'mounted', 'before_update', 'updated', 'before_unmount')
  • callback: A function that takes the component as a parameter

Example:

def on_mounted(component):
    print("Component mounted")

component.on('mounted', on_mounted)

render() -> str

Renders the component to HTML. This method must be implemented by subclasses.

Returns:

  • The rendered HTML as a string

Example:

class MyComponent(Component):
    def render(self):
        return "<div>Hello, World!</div>"

TailwindIntegration Class

The TailwindIntegration class provides helpers for Tailwind CSS integration.

Static Methods

setup(project_path: str) -> None

Sets up Tailwind CSS in a project.

Parameters:

  • project_path: The path to the project directory

Example:

from snakeskin import TailwindIntegration

TailwindIntegration.setup("./my-project")

build(output_path: str = "./dist/tailwind.css", minify: bool = True) -> None

Builds Tailwind CSS.

Parameters:

  • output_path: The path where the CSS file will be written
  • minify: Whether to minify the CSS

Example:

TailwindIntegration.build("./dist/styles.css", minify=True)

BootstrapIntegration Class

The BootstrapIntegration class provides helpers for Bootstrap integration.

Static Methods

setup(project_path: str) -> None

Sets up Bootstrap in a project.

Parameters:

  • project_path: The path to the project directory

Example:

from snakeskin import BootstrapIntegration

BootstrapIntegration.setup("./my-project")

get_cdn_links() -> dict

Gets Bootstrap CDN links for CSS and JS.

Returns:

  • A dictionary with 'css' and 'js' keys containing the HTML tags

Example:

links = BootstrapIntegration.get_cdn_links()
css_link = links['css']
js_script = links['js']

include_in_template(template: str, position: str = "head") -> str

Includes Bootstrap in an HTML template.

Parameters:

  • template: The HTML template
  • position: Where to include Bootstrap ('head', 'body', or 'both')

Returns:

  • The modified HTML template

Example:

html = """
<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
</head>
<body>
    <div id="app"></div>
</body>
</html>
"""

bootstrap_html = BootstrapIntegration.include_in_template(html, "both")

CLI Commands

Snakeskin provides several CLI commands for project management.

snakeskin create <project-name>

Creates a new Snakeskin project.

Parameters:

  • project-name: The name of the project to create

Example:

snakeskin create my-project

snakeskin dev

Starts the development server with hot reload.

Example:

snakeskin dev

snakeskin build

Builds the project for production.

Example:

snakeskin build

Lifecycle Hooks

Snakeskin components have several lifecycle hooks:

Hook Description
before_mount Called before the component is mounted
mounted Called after the component is mounted
before_update Called before the component's state is updated
updated Called after the component's state is updated
before_unmount Called before the component is unmounted

Example:

from snakeskin.framework import Component

class LifecycleComponent(Component):
    def __init__(self, **props):
        super().__init__(**props)
        
        # Register lifecycle hooks
        self.on('before_mount', self.on_before_mount)
        self.on('mounted', self.on_mounted)
        self.on('before_update', self.on_before_update)
        self.on('updated', self.on_updated)
        self.on('before_unmount', self.on_before_unmount)
    
    def on_before_mount(self, component):
        print("Before mount")
    
    def on_mounted(self, component):
        print("Mounted")
    
    def on_before_update(self, component):
        print("Before update")
    
    def on_updated(self, component):
        print("Updated")
    
    def on_before_unmount(self, component):
        print("Before unmount")
    
    def render(self):
        return "<div>Lifecycle Component</div>"

Error Handling

Snakeskin provides several ways to handle errors:

Component Error Handling

from snakeskin.framework import Component

class ErrorHandlingComponent(Component):
    def __init__(self, **props):
        super().__init__(**props)
        self.state = {"error": None, "data": None}
    
    def fetch_data(self):
        try:
            # Simulate API call
            data = {"name": "Example"}
            self.set_state({"data": data, "error": None})
        except Exception as e:
            self.set_state({"error": str(e), "data": None})
    
    def render(self):
        if self.state.get("error"):
            return f"""
            <div class="error">
                <h2>Error</h2>
                <p>{self.state["error"]}</p>
            </div>
            """
        elif self.state.get("data"):
            return f"""
            <div class="data">
                <h2>Data</h2>
                <p>{self.state["data"]["name"]}</p>
            </div>
            """
        else:
            return """
            <div class="loading">
                <p>Loading...</p>
            </div>
            """

Global Error Handling

You can implement a global error handler for your application:

# error_handler.py
class ErrorHandler:
    def __init__(self):
        self.errors = []
        self.error_callbacks = []
    
    def capture_error(self, error, component=None):
        error_info = {
            "error": error,
            "component": component.__class__.__name__ if component else None,
            "timestamp": time.time()
        }
        self.errors.append(error_info)
        self._notify_callbacks(error_info)
        
        # Log the error
        print(f"Error in {error_info['component']}: {error}")
    
    def add_callback(self, callback):
        self.error_callbacks.append(callback)
    
    def _notify_callbacks(self, error_info):
        for callback in self.error_callbacks:
            callback(error_info)

# Create a singleton instance
error_handler = ErrorHandler()
# In your component
from error_handler import error_handler

class ComponentWithErrorHandling(Component):
    def risky_operation(self):
        try:
            # Some risky operation
            result = 1 / 0  # Will raise ZeroDivisionError
            return result
        except Exception as e:
            error_handler.capture_error(e, self)
            return None

Troubleshooting

For common issues and their solutions, see the Troubleshooting Guide.