chore: Port TypeScript codebase

.claude/CLAUDE.md

@@ -12,11 +12,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Commands
 
+- Run `uv run task install` to install all dependencies
 - Run `uv run task lint` to lint the code using Ruff
 - Run `uv run task format` to auto-fix formatting issues with Ruff
 - Run `uv run task type` to run type checking
-- Run `uv run task test` to run the full test suite including linting, type checking, and tests
 - Run `uv run task spec` to run only the pytest tests
+- Run `uv run task test` to run the full test suite (lint/type/spec)
 - Run `uv run pytest path/to/test.py` to run a single test file
 - Run `uv run pytest -k "test name"` to run a single test by name
 

.github/ISSUE_TEMPLATE/01-bug-report.yaml

@@ -0,0 +1,30 @@
+name: "🐞 Bug Report"
+description: Report an issue or possible bug
+labels: []
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to file a bug report! Please fill out this form as completely as possible.
+  - type: input
+    id: version
+    attributes:
+      label: What version are you using?
+      placeholder: 1.0.0
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the Bug
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Participation
+      options:
+        - label: I am willing to submit a pull request for this issue.
+          required: false

.github/ISSUE_TEMPLATE/02-general-issue.yaml

@@ -0,0 +1,30 @@
+name: "🌳 General Issue"
+description: Project, website, or documentation related issue or improvement
+labels: []
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to improve the project! Please fill out this form as completely as possible.
+  - type: input
+    id: version
+    attributes:
+      label: What version are you using?
+      placeholder: 1.0.0
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the Issue
+      description: A clear and concise description of what the issue or possible improvement is.
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Participation
+      options:
+        - label: I am willing to submit a pull request for this issue.
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 👀 Explore Discussions
+    url: https://github.com/orgs/fairspec/discussions
+    about: Before opening a discussion, please check if the topic has already been discussed. Please vote on existing discussions to show your support.
+  - name: 💡 Feature Request
+    url: https://github.com/orgs/fairspec/discussions/new?category=ideas
+    about: Suggest an improvement you'd like to see added to Fairspec Python
+  - name: 🚀 Implementation
+    url: https://github.com/orgs/fairspec/discussions/new?category=show-and-tell
+    about: Share your Fairspec Python related project with the community
+  - name: 💁 Question
+    url: https://github.com/orgs/fairspec/discussions/new?category=q-a
+    about: Ask a question about Fairspec Python

.github/codecov.yaml

@@ -0,0 +1,11 @@
+comment: no
+
+coverage:
+  range: 80..90
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true

.github/workflows/general.yaml

@@ -0,0 +1,103 @@
+name: general
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test-linux:
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install Dependencies
+        run: uv run task install
+      - name: Test Packages
+        run: uv run task test
+      - name: Upload Coverage
+        uses: codecov/codecov-action@v5
+        with:
+          use_oidc: true
+
+  test-macos:
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install Dependencies
+        run: uv run task install
+      - name: Test Packages
+        run: uv run task test
+
+  test-windows:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v5
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install Dependencies
+        run: uv run task install
+      - name: Test Packages
+        run: uv run task test
+
+  release:
+    needs: [test-linux, test-macos, test-windows]
+    environment: release
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && !contains(github.ref, 'refs/tags/')
+
+    outputs:
+      created: ${{ steps.release.outputs.new_release_published }}
+      version: ${{ steps.release.outputs.new_release_version }}
+
+    permissions:
+      id-token: write
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install Dependencies
+        run: uv run task install
+      - name: Release Packages
+        uses: python-semantic-release/python-semantic-release@v9
+        id: release
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -214,3 +214,16 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Node
+node_modules/
+jspm_packages/
+.lock-wscript
+build/Release
+.node_repl_history
+*.tgz
+.npm
+*.so
+
+# User
+/.claude/settings.local.json

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+  - repo: local
+    hooks:
+      - id: test
+        name: test
+        entry: uv run task test
+        language: system
+        always_run: true
+        pass_filenames: false
+        stages: [pre-push]

dataset/README.md

@@ -0,0 +1,3 @@
+# fairspec-dataset
+
+Fairspec Python is a fast data management framework built on top of the Fairspec standard and Polars DataFrames. It supports various formats like CSV, JSON, and Parquet and integrates with data platforms such as CKAN, Zenodo, and GitHub. For more information, please read the [project's documentation](https://python.fairspec.org).

dataset/fairspec_dataset/__init__.py

@@ -0,0 +1,92 @@
+from .actions.dataset.basepath import get_common_local_basepath, get_dataset_basepath
+from .actions.dataset.merge import merge_datasets
+from .actions.file.copy import copy_file
+from .actions.file.describe import describe_file
+from .models.file import FileDescription
+from .actions.file.infer import infer_bytes, infer_hash, infer_integrity, infer_textual
+from .actions.file.load import load_file
+from .actions.file.path import assert_local_path_vacant, get_is_local_path_exist
+from .actions.file.prefetch import prefetch_file, prefetch_files
+from .actions.file.save import save_file
+from .actions.file.temp import get_temp_file_path, write_temp_file
+from .actions.file.validate import validate_file
+from .actions.folder.create import create_folder
+from .actions.folder.temp import get_temp_folder_path
+from .actions.resource.save import SaveFileCallback, SaveFileProps, save_resource_files
+from .actions.stream.concat import concat_file_streams
+from .actions.stream.load import load_file_stream
+from .actions.stream.save import save_file_stream
+from .models.dataset import SaveDatasetOptions
+from .models.file_dialect import InferFileDialectOptions
+from .models.dataset import SaveDatasetResult
+from .plugin import DatasetPlugin
+from .plugins.descriptor import DescriptorPlugin
+from .plugins.ckan import CkanPlugin, load_dataset_from_ckan, save_dataset_to_ckan
+from .plugins.folder import (
+    FolderPlugin,
+    load_dataset_from_folder,
+    save_dataset_to_folder,
+)
+from .plugins.github import (
+    GithubPlugin,
+    load_dataset_from_github,
+    save_dataset_to_github,
+)
+from .plugins.zenodo import (
+    ZenodoPlugin,
+    load_dataset_from_zenodo,
+    save_dataset_to_zenodo,
+)
+from .plugins.zip import ZipPlugin, load_dataset_from_zip, save_dataset_to_zip
+from fairspec_metadata.plugin import MetadataPlugin
+
+__all__ = [
+    "CkanPlugin",
+    "DatasetPlugin",
+    "DescriptorPlugin",
+    "FileDescription",
+    "FolderPlugin",
+    "GithubPlugin",
+    "InferFileDialectOptions",
+    "MetadataPlugin",
+    "SaveDatasetOptions",
+    "SaveDatasetResult",
+    "SaveFileCallback",
+    "SaveFileProps",
+    "ZenodoPlugin",
+    "ZipPlugin",
+    "assert_local_path_vacant",
+    "concat_file_streams",
+    "copy_file",
+    "create_folder",
+    "describe_file",
+    "get_common_local_basepath",
+    "get_dataset_basepath",
+    "get_is_local_path_exist",
+    "get_temp_file_path",
+    "get_temp_folder_path",
+    "infer_bytes",
+    "infer_hash",
+    "infer_integrity",
+    "infer_textual",
+    "load_dataset_from_ckan",
+    "load_dataset_from_folder",
+    "load_dataset_from_github",
+    "load_dataset_from_zenodo",
+    "load_dataset_from_zip",
+    "load_file",
+    "load_file_stream",
+    "merge_datasets",
+    "prefetch_file",
+    "prefetch_files",
+    "save_dataset_to_ckan",
+    "save_dataset_to_folder",
+    "save_dataset_to_github",
+    "save_dataset_to_zenodo",
+    "save_dataset_to_zip",
+    "save_file",
+    "save_file_stream",
+    "save_resource_files",
+    "validate_file",
+    "write_temp_file",
+]