feat: gather common classes for trame

Author: jourdain

.codespellrc

@@ -0,0 +1,2 @@
+[codespell]
+skip = CHANGELOG.md

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  # Maintain dependencies for GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    groups:
+      actions:
+        patterns:
+          - "*"

.github/release.yml

@@ -0,0 +1,5 @@
+changelog:
+  exclude:
+    authors:
+      - dependabot
+      - pre-commit-ci

.github/workflows/test_and_release.yml

@@ -0,0 +1,103 @@
+name: Test and Release
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
+  FORCE_COLOR: 3
+
+jobs:
+  pre-commit:
+    name: Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - uses: pre-commit/action@v3.0.1
+        with:
+          extra_args: --hook-stage manual --all-files
+      - name: Run Lint
+        run: pipx run nox -s lint
+      - name: Run Tests
+        run: pipx run nox -s tests
+
+  checks:
+    name: Check Python ${{ matrix.python-version }} on ${{ matrix.runs-on }}
+    runs-on: ${{ matrix.runs-on }}
+    needs: [pre-commit]
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.13"]
+        runs-on: [ubuntu-latest, windows-latest, macos-14]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      - name: Install package
+        run: python -m pip install .[test]
+
+      - name: Test package
+        run: >-
+          python -m pytest -ra --cov --cov-report=xml --cov-report=term
+          --durations=20
+
+      - name: Upload coverage report
+        uses: codecov/codecov-action@v5.4.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  release:
+    needs: [pre-commit, checks]
+    name: Distribution build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    permissions:
+      id-token: write
+      attestations: write
+      contents: write
+    environment:
+      name: pypi
+      url: https://pypi.org/p/trame-common
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v9.21.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # for debug output
+          # root_options: "-vv"
+
+      - name: Generate artifact attestation for sdist and wheel
+        if: steps.release.outputs.released == 'true'
+        uses: actions/attest-build-provenance@v2.2.3
+        with:
+          subject-path: "dist/*"
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.release.outputs.released == 'true'

.pre-commit-config.yaml

@@ -0,0 +1,80 @@
+ci:
+  autoupdate_commit_msg: "chore: update pre-commit hooks"
+  autofix_commit_msg: "style: pre-commit fixes"
+
+exclude: ^.cruft.json|.copier-answers.yml$
+
+repos:
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: "1.19.1"
+    hooks:
+      - id: blacken-docs
+        additional_dependencies: [black==24.*]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v5.0.0"
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-yaml
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: name-tests-test
+        args: ["--pytest-test-first"]
+      - id: requirements-txt-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/pre-commit/pygrep-hooks
+    rev: "v1.10.0"
+    hooks:
+      - id: rst-backticks
+      - id: rst-directive-colons
+      - id: rst-inline-touching-normal
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: "v3.4.2"
+    hooks:
+      - id: prettier
+        types_or: [yaml, markdown, html, css, scss, javascript, json]
+        args: [--prose-wrap=always]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.9.1"
+    hooks:
+      - id: ruff
+        args: ["--fix", "--show-fixes"]
+      - id: ruff-format
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: "v2.3.0"
+    hooks:
+      - id: codespell
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: "v0.10.0.1"
+    hooks:
+      - id: shellcheck
+
+  - repo: local
+    hooks:
+      - id: disallow-caps
+        name: Disallow improper capitalization
+        language: pygrep
+        entry: PyBind|Numpy|Cmake|CCache|Github|PyTest
+        exclude: .pre-commit-config.yaml
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: "v0.23"
+    hooks:
+      - id: validate-pyproject
+        additional_dependencies: ["validate-pyproject-schema-store[all]"]
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: "0.31.0"
+    hooks:
+      - id: check-dependabot
+      - id: check-github-workflows
+      - id: check-readthedocs

.prettierignore

@@ -0,0 +1 @@
+CHANGELOG.md

README.md

@@ -0,0 +1,64 @@
+# trame-common: common code for any trame package
+
+Trame is rapidly evolving and having a dependency-less package to provide helper
+functions and classes across trame's eco-system is important for its future
+health. Initially some of those classes were created inside **trame-client**,
+**trame-server** or even **trame**, but we reached a point where some of those
+should become even more mainstream so they could easily be used on server,
+client, widget and more. That is where **trame-common** comes to play by
+providing a central location that any package can depend on. By default,
+**trame** remain the meta package that will impose some minimum version on
+**trame-common**, **trame-client** and **trame-server** and expose via some
+common namespace various pieces of those 3 dependencies. But if you need any
+piece of **trame-common**, feel free to depend on it.
+
+Trame-common is not meant to be installed by itself, but instead be used by any
+trame package that may require one of its function or helper class. While some
+of the module may require extra dependency, we are not listing them in this
+package purposely but the using code, should properly describe such dependency.
+
+## Content
+
+**trame-common** is composed of several packages to split the current set of
+classes and function in meaningful groups.
+
+- **trame_common.assets**: Contains anything related to local and remote file
+  including possible associated mime types.
+- **trame_common.decorators**: Contains all decorators for functions, classes
+  and methods.
+- **trame_common.exec**: Contains helpers for handling code execution (i.e.
+  async, throttle, debounce, thread, process).
+- **trame_common.obj**: Contains helpers for common trame objects (i.e.
+  Component, App, Widget, Singleton)
+
+## License
+
+trame-common is made available under the Apache License, Version 2.0. For more
+details, see
+[LICENSE](https://github.com/Kitware/trame-common/blob/master/LICENSE).
+
+## Development steps
+
+- Clone the repository using `git clone`
+- Install pre-commit via `pip install pre-commit` or `pip install -e ".[dev]"`
+- Run `pre-commit install` to set up pre-commit hooks
+- Run `pre-commit install --hook-type commit-msg` to register commit-msg hook
+- Make changes to the code, and commit your changes to a separate branch. Use
+  [conventional commit messages](https://www.conventionalcommits.org/en/v1.0.0/).
+- Create a fork of the repository on GitHub
+- Push your branch to your fork, and open a pull request
+
+**Tips**
+
+- When first creating a new project, it is helpful to run
+  `pre-commit run --all-files` to ensure all files pass the pre-commit checks.
+- A quick way to fix `ruff` issues is by installing ruff (`pip install ruff`)
+  and running the `ruff check --fix .` or `ruff format` command at the root of
+  your repository.
+- A quick way to fix `codespell` issues is by installing codespell
+  (`pip install codespell`) and running the `codespell -w` command at the root
+  of your directory.
+- The
+  `.codespellrc file <https://github.com/codespell-project/codespell#using-a-config-file>`\_
+  can be used fix any other codespell issues, such as ignoring certain files,
+  directories, words, or regular expressions.

noxfile.py

@@ -0,0 +1,44 @@
+import shutil
+from pathlib import Path
+
+import nox
+
+DIR = Path(__file__).parent.resolve()
+
+nox.needs_version = ">=2024.3.2"
+nox.options.sessions = ["lint", "tests"]
+nox.options.default_venv_backend = "uv|virtualenv"
+
+
+@nox.session
+def lint(session: nox.Session) -> None:
+    """
+    Run the linter.
+    """
+    session.install("pre-commit")
+    session.run(
+        "pre-commit", "run", "--all-files", "--show-diff-on-failure", *session.posargs
+    )
+
+
+@nox.session
+def tests(session: nox.Session) -> None:
+    """
+    Run the unit and regular tests.
+    """
+    session.install(".[test]")
+    session.run("pytest", *session.posargs)
+
+
+@nox.session
+def build(session: nox.Session) -> None:
+    """
+    Build an SDist and wheel.
+    """
+
+    build_path = DIR.joinpath("build")
+    if build_path.exists():
+        shutil.rmtree(build_path)
+
+    session.install("build")
+    session.run("python", "-m", "build")