Skip to content

Contributing to PyDataUI

Thank you for your interest in contributing to PyDataUI! As an open-source framework, PyDataUI thrives because of contributors like youβ€”whether you are writing code, fixing typos in docs, adding real-world examples, or suggesting architectural improvements.


πŸš€ Quickstart for Contributors

1. Fork & Clone

git clone https://github.com/rajboopathiking/pydataui.git
cd pydataui

2. Set Up Virtual Environment

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install package in editable mode with development & documentation extras
pip install --upgrade pip
pip install -e ".[dev,docs]"

3. Verify Existing Tests

pytest tests/ -q --ignore=tests/test_browser_security.py
All unit tests should pass with 0 failures before you start making changes.


πŸ›οΈ Repository Architecture

PyDataUI is organized into modular packages under pydataui/:

pydataui/
β”œβ”€β”€ __init__.py           # Public exports (App, state, Shad*, Card, DataTable, etc.)
β”œβ”€β”€ app.py                # App lifecycle, routing, FastAPI integration, middleware
β”œβ”€β”€ state.py              # Reactive Proxy state system & action dispatchers
β”œβ”€β”€ tui.py                # Terminal UI renderer (Rich & ASCII REPL fallback)
β”œβ”€β”€ config.py             # Global AppConfig and environment variable overrides
β”œβ”€β”€ api.py                # Automatic OpenAPI/REST endpoint generator
β”œβ”€β”€ session.py            # Isolated per-client state session manager
β”œβ”€β”€ event.py              # Event triggers & client-server RPC signals
β”œβ”€β”€ auth/                 # JWT tokens, RBAC, password hashing, and user models
β”‚   β”œβ”€β”€ manager.py        # AuthManager
β”‚   β”œβ”€β”€ models.py         # User, Role, APIKey dataclasses
β”‚   └── decorators.py     # @require_auth, @require_role, @require_api_key
β”œβ”€β”€ compiler/             # SSR AST compiler & HTML templates
β”‚   β”œβ”€β”€ renderer.py       # Compiles component trees to optimized HTML
β”‚   └── templates.py      # Base HTML shell with Tailwind CSS & HTMX
β”œβ”€β”€ components/           # 80+ UI components
β”‚   β”œβ”€β”€ base.py           # Component base class & life cycle
β”‚   β”œβ”€β”€ shadcn.py         # Modern shadcn/ui inspired primitives
β”‚   β”œβ”€β”€ data_science.py   # Universal DataTable, Plotly charts, Metrics
β”‚   β”œβ”€β”€ layout.py         # Container, Row, Col, Grid, Card
β”‚   └── forms.py          # Input, Button, Slider, Select, Switch
└── styling/              # Embedded static assets
    β”œβ”€β”€ css/pydataui.css  # Framework stylesheet
    └── js/htmx.min.js    # Embedded HTMX runtime

πŸ› οΈ Step-by-Step: Adding a New Component

Every component in PyDataUI inherits from Component in pydataui.components.base.

Step 1: Define the Component Class

from typing import Optional, List, Dict, Any
from pydataui.components.base import Component
from pydataui.utils import escape_html

class ShadKpiCard(Component):
    """A high-contrast KPI metric card with trend badge."""

    def __init__(
        self,
        title: str,
        value: Any,
        trend: Optional[str] = None,
        is_positive: bool = True,
        **kwargs
    ):
        super().__init__(**kwargs)
        self.title = title
        self.value = value
        self.trend = trend
        self.is_positive = is_positive

    def render(self, state_snapshot: Optional[Dict[str, Any]] = None) -> str:
        # Resolve reactive state variables if passed
        resolved_val = self.value.resolve(state_snapshot) if hasattr(self.value, 'resolve') else self.value

        trend_badge = ""
        if self.trend:
            color_cls = "text-emerald-500 bg-emerald-50 dark:bg-emerald-950/40" if self.is_positive else "text-rose-500 bg-rose-50 dark:bg-rose-950/40"
            trend_badge = f'<span class="text-xs font-semibold px-2 py-0.5 rounded-full {color_cls}">{escape_html(self.trend)}</span>'

        return f'''
        <div class="p-6 rounded-xl border border-border bg-card text-card-foreground shadow-sm">
            <div class="flex items-center justify-between space-y-0 pb-2">
                <span class="text-sm font-medium text-muted-foreground">{escape_html(self.title)}</span>
                {trend_badge}
            </div>
            <div class="text-2xl font-bold tracking-tight">{escape_html(str(resolved_val))}</div>
        </div>
        '''

Step 2: Register & Export

Add the component to pydataui/components/__init__.py and pydataui/__init__.py.

Step 3: Add Unit Tests

Create a test in tests/test_components.py:

def test_shad_kpi_card():
    from pydataui import ShadKpiCard, state
    s = state(revenue=50000)
    card = ShadKpiCard("Quarterly Revenue", s.revenue, trend="+12.4%", is_positive=True)
    html = card.render()
    assert "Quarterly Revenue" in html
    assert "50000" in html
    assert "+12.4%" in html


πŸ§ͺ Testing Guidelines

  1. Fast Unit Tests:
    pytest tests/ -q --ignore=tests/test_browser_security.py
    
  2. Headless Browser Tests: Browser tests run Playwright against a live Chromium instance:
    pip install -e ".[browser]"
    python -m playwright install --with-deps chromium
    pytest tests/test_browser_security.py -v
    
  3. No Flaky Tests: Tests must be deterministic and never depend on external live networks or unbounded sleeps.

πŸ“– Documentation Standards

All PyDataUI documentation is written in Material for MkDocs.

Rules for Documentation:

  1. Pure Markdown Only: Do NOT check in raw HTML pages (.html) as primary documentation files. All docs must be .md.
  2. Brand Hygiene: Never use legacy or personal project names in code, examples, or docs. Always use pydataui or PyDataUI Platform.
  3. Local Docs Preview:
    mkdocs serve
    
  4. Strict Build Validation: Before committing, verify that there are zero warnings and zero broken links:
    mkdocs build --strict
    

πŸ”€ Pull Request Lifecycle

flowchart LR
    A[Fork & Branch] --> B[Implement Feature / Fix]
    B --> C[Run Pytest & MkDocs Strict]
    C --> D[Open Pull Request]
    D --> E[Automated CI Matrix Pass]
    E --> F[Code Review & Merge]
  1. Branch Naming:
  2. feat/add-stepper-component
  3. fix/tui-session-leak
  4. docs/add-duckdb-guide
  5. Commit Messages: Follow Conventional Commits:
  6. feat: add ShadKpiCard metric component
  7. fix: resolve TUI ASCII header output
  8. docs: add comprehensive contribution guide
  9. Checklist Before Submitting:
  10. [x] Code passes pytest.
  11. [x] mkdocs build --strict exits 0.
  12. [x] Type hints included for all public API functions.
  13. [x] PR description references the related issue.