tabulynx 0.1.0__tar.gz

tabulynx-0.1.0/.github/workflows/publish-python-package.yml

@@ -0,0 +1,190 @@
+name: Publish Python Package
+
+on:
+  push:
+    branches:
+      - development
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-development
+  cancel-in-progress: false
+
+jobs:
+  prepare:
+    name: Prepare Release
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:python3.12-bookworm
+    outputs:
+      should_release: ${{ steps.version.outputs.should_release }}
+      version: ${{ steps.version.outputs.version }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Detect version bump
+        id: version
+        shell: bash
+        run: |
+          current_version="$(python -c 'import tomllib; from pathlib import Path; data = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8")); print(data["project"]["version"])')"
+          echo "version=$current_version" >> "$GITHUB_OUTPUT"
+
+          previous_ref="${{ github.event.before }}"
+          if [ -n "$previous_ref" ] && git cat-file -e "${previous_ref}:pyproject.toml" 2>/dev/null; then
+            previous_version="$(git show "${previous_ref}:pyproject.toml" | python -c 'import sys, tomllib; data = tomllib.loads(sys.stdin.read()); print(data["project"]["version"])')"
+          else
+            previous_version=""
+          fi
+
+          if [ "$current_version" = "$previous_version" ]; then
+            echo "No version bump detected. Skipping release."
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if git rev-parse "refs/tags/v${current_version}" >/dev/null 2>&1; then
+            echo "Tag v${current_version} already exists." >&2
+            exit 1
+          fi
+
+          echo "should_release=true" >> "$GITHUB_OUTPUT"
+
+  test_build:
+    name: Test & Build
+    needs: prepare
+    if: needs.prepare.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:python3.12-bookworm
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Create venv
+        run: uv venv
+
+      - name: Install project + dev deps
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs:
+      - prepare
+      - test_build
+    if: needs.prepare.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:python3.12-bookworm
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        run: uv publish dist/* --token ${{ secrets.PYPI_API_TOKEN }}
+
+  tag_release:
+    name: Tag Release
+    needs:
+      - prepare
+      - publish
+    if: needs.prepare.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Create release tag
+        shell: bash
+        run: |
+          version="${{ needs.prepare.outputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "v${version}" "${GITHUB_SHA}"
+          git push origin "v${version}"
+
+  github_release:
+    name: Create GitHub Release
+    needs:
+      - prepare
+      - tag_release
+    if: needs.prepare.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Build release notes
+        shell: bash
+        run: |
+          version="${{ needs.prepare.outputs.version }}"
+          previous_tag="$(git tag --sort=-version:refname | grep -v "^v${version}$" | head -n 1)"
+          version_notes="release-notes/v${version}.md"
+
+          if [ -f "$version_notes" ]; then
+            cp "$version_notes" release-notes.md
+          else
+            {
+              echo "## Release"
+              echo
+              echo "This release is published to PyPI."
+              echo
+              echo "Install with:"
+              echo
+              echo "\`\`\`bash"
+              echo "pip install -U tabulynx"
+              echo "\`\`\`"
+            } > release-notes.md
+          fi
+
+          if [ -n "$previous_tag" ]; then
+            {
+              echo
+              echo "## Full Changelog"
+              echo
+              echo "https://github.com/${{ github.repository }}/compare/${previous_tag}...v${version}"
+            } >> release-notes.md
+          fi
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          gh release create "v${{ needs.prepare.outputs.version }}" \
+            --notes-file release-notes.md \
+            --title "v${{ needs.prepare.outputs.version }}"

tabulynx-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+.pytest_cache/
+.uv-cache/
+.idea/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+build/
+dist/
+.coverage
+htmlcov/

tabulynx-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

tabulynx-0.1.0/PKG-INFO

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: tabulynx
+Version: 0.1.0
+Summary: Desktop spreadsheet-style viewer for CSV, XLSX, and Parquet files
+Project-URL: Homepage, https://github.com/Jeferson-Peter/tabulynx
+Project-URL: Repository, https://github.com/Jeferson-Peter/tabulynx
+Project-URL: Issues, https://github.com/Jeferson-Peter/tabulynx/issues
+Keywords: csv,desktop,parquet,polars,qt,spreadsheet,xlsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications :: Qt
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: fastexcel>=0.11.5
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: polars>=1.12.0
+Requires-Dist: pyside6>=6.8.0
+Description-Content-Type: text/markdown
+
+# TabuLynx
+
+TabuLynx is a local desktop spreadsheet-style viewer for tabular files. It is meant for opening, exploring, filtering, sorting, querying, and exporting local datasets without starting a web server or using a full spreadsheet suite.
+
+It supports:
+
+- CSV
+- XLSX
+- Parquet
+
+The core is built on `polars`, and the desktop interface is built with `PySide6`.
+
+## Features
+
+- Native desktop table viewer for local tabular files
+- Data-type aware filters for text, numbers, booleans, dates, and datetimes
+- Multi-filter and multi-sort support
+- Global search across columns
+- Column visibility controls
+- Explicit pagination with configurable page size
+- Row details side panel
+- Column statistics side panel
+- Dataset summary side panel
+- Export of the current view to CSV or Parquet
+- SQL queries against the current view using Polars SQL
+- Temporary SQL result tabs
+- SQL examples, SQL clear action, and local SQL history
+- Query presets
+- Multiple files in tabs
+- Recent files and pinned files
+- Last-session restore
+- Query history per tab with back/forward navigation
+- Context menu actions on cells and headers
+- Optimized XLSX browsing through cached Parquet conversion
+- Keyboard shortcuts for common actions
+
+## Quick Start
+
+Install dependencies:
+
+```bash
+uv sync
+```
+
+Run the desktop app:
+
+```bash
+uv run tabulynx
+```
+
+Open a file directly:
+
+```bash
+uv run tabulynx open ./your-file.csv
+```
+
+You can also open:
+
+```bash
+uv run tabulynx open ./your-file.xlsx
+uv run tabulynx open ./your-file.parquet
+```
+
+## Basic Workflow
+
+1. Open a `csv`, `xlsx`, or `parquet` file.
+2. Use the global search box to quickly reduce the visible rows.
+3. Add filters and sorts from the query area.
+4. Use the `Columns` menu to show or hide columns.
+5. Select a row to inspect full row values in the side panel.
+6. Click a column header to view column statistics.
+7. Use `Export` to save the current view as CSV or Parquet.
+
+The current view means the result after applying search, filters, sorts, and visible columns.
+
+## SQL Support
+
+The SQL panel uses Polars SQL and runs against the current tab's current view. The available table name is always `current`.
+
+Example:
+
+```sql
+SELECT customer, revenue
+FROM current
+WHERE revenue > 100
+ORDER BY revenue DESC
+LIMIT 50
+```
+
+Supported today:
+
+- Querying the current tab as `current`
+- `SELECT`, `WHERE`, `ORDER BY`, `LIMIT`, and common Polars SQL expressions supported by Polars
+- Aggregations and grouping supported by Polars SQL
+- SQL over the current view, so active search, filters, sorts, and visible columns are applied before the SQL query runs
+- Opening SQL results as temporary result tabs
+- Quick SQL examples
+- Local SQL history
+
+Not supported yet:
+
+- Cross-tab SQL queries or joins between multiple open files
+- Persistent SQL result tabs across app restarts
+- SQL editing of source files
+- Database features such as indexes, transactions, stored procedures, or user-defined SQL functions
+- Full DuckDB/PostgreSQL-style SQL compatibility
+
+## XLSX Handling
+
+Excel files are handled differently from CSV and Parquet.
+
+For `xlsx`, TabuLynx:
+
+- Discovers sheet names up front
+- Lets you switch sheets in the desktop UI
+- Opens workbooks with a read-only ingestion path
+- Converts the selected sheet into cached Parquet
+- Uses the cached Parquet file for faster browsing, filtering, sorting, SQL, and pagination
+
+This keeps the UI experience consistent while avoiding repeated direct Excel reads during exploration.
+
+Important notes:
+
+- The first open of a large sheet may take longer while the cache is created.
+- The cache is invalidated when the source file metadata changes.
+- Excel formulas are read as stored values when available.
+- TabuLynx does not recalculate Excel formulas.
+- TabuLynx does not preserve Excel formatting, formulas, merged cells, charts, or styles during export.
+
+## Keyboard Shortcuts
+
+- `Ctrl+O`: open file
+- `Ctrl+F`: focus global search
+- `Ctrl+Enter`: run SQL in the current tab
+- `Esc`: clear filters in the current tab
+- Double-click a column header divider: autosize the column
+
+## Context Menus
+
+Right-click a table cell for quick actions such as:
+
+- Copy cell
+- Copy row
+- Filter by selected value
+- Search/filter by selected text
+- Hide the clicked column
+
+Right-click a column header for quick column actions such as:
+
+- Search in that column
+- Clear filters for that column
+- Sort ascending or descending
+- Hide the column
+
+## Presets, Recent Files, And Session State
+
+TabuLynx stores local app state under `~/.tabulynx/`.
+
+Current local state includes:
+
+- Query presets
+- SQL history
+- Recent files
+- Pinned files
+- Last-session restore data
+- XLSX Parquet cache
+
+The app state is local to your machine and is not synced or uploaded by TabuLynx.
+
+## Library Usage
+
+You can also use the core library directly:
+
+```python
+from tabulynx import open_dataset
+
+dataset = open_dataset("your-file.xlsx", sheet="Sheet1")
+
+print(dataset.columns())
+print(dataset.row_count())
+print(dataset.page(0, 100))
+```
+
+Apply filters and sorts:
+
+```python
+from tabulynx.core import ColumnFilter, SortRule, open_dataset
+
+dataset = open_dataset("your-file.parquet")
+dataset.add_filter(ColumnFilter(column="revenue", operator="gte", value="100"))
+dataset.set_sorts([SortRule(column="revenue", descending=True)])
+
+page = dataset.page(offset=0, limit=50)
+print(page.rows)
+```
+
+Run SQL from Python:
+
+```python
+dataset = open_dataset("your-file.csv")
+
+result = dataset.sql_query(
+    """
+    SELECT customer, SUM(revenue) AS total_revenue
+    FROM current
+    GROUP BY customer
+    ORDER BY total_revenue DESC
+    """
+)
+
+print(result)
+```
+
+## Sample Data
+
+Sample data for local testing lives in:
+
+- `sample_data/filters_demo.csv`
+- `sample_data/filters_demo.parquet`
+
+Regenerate the sample files:
+
+```bash
+uv run python scripts/create_sample_data.py
+```
+
+Generate a larger sample:
+
+```bash
+uv run python scripts/create_sample_data.py --rows 20000
+```
+
+## Run Tests
+
+Install development dependencies:
+
+```bash
+uv sync --group dev
+```
+
+Run the test suite:
+
+```bash
+uv run pytest -q
+```
+
+## Project Structure
+
+```text
+src/tabulynx/
+  __init__.py
+  __main__.py
+  cli.py
+  core.py
+  qt.py
+  viewer.py
+
+sample_data/
+  filters_demo.csv
+  filters_demo.parquet
+
+scripts/
+  create_sample_data.py
+
+tests/
+  test_core.py
+```
+
+## Current Limitations
+
+- TabuLynx is a viewer and exploration tool, not a full spreadsheet editor.
+- It does not currently edit cells or save changes back into the original source file.
+- XLSX support uses cached Parquet conversion per selected sheet; very large or irregular workbooks may take time on first open.
+- Excel formulas are not recalculated by TabuLynx.
+- Excel formatting, styles, merged cells, charts, and workbook-specific layout features are not preserved.
+- SQL currently runs only against the current tab's current view as the table `current`.
+- SQL result tabs are temporary and are not restored in the next session.
+- Cross-tab SQL joins are not supported yet.
+- Extremely large datasets may still depend on available memory and local disk cache.
+- The UI is focused on desktop use and is not intended for browser or mobile workflows.
+
+## Roadmap Ideas
+
+- Cross-tab SQL queries
+- Better SQL editor experience
+- More test coverage for UI state and Excel edge cases
+- More robust XLSX type inference for irregular workbooks
+- Optional app packaging with PyInstaller or Nuitka
+- Screenshots and release packaging documentation