trame-code 1.0.1__tar.gz → 1.1.0__tar.gz

trame_code-1.1.0/.codespellrc

@@ -0,0 +1,2 @@
+[codespell]
+skip = **/package-lock.json,example/textmate/langs/**

trame_code-1.1.0/.github/workflows/test_and_release.yml

@@ -0,0 +1,122 @@
+name: Test and Release
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON: "3.12"
+    steps:
+      - uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.12"
+          enable-cache: true
+      - name: Install the project
+        run: uv sync --all-extras --dev
+
+      # Install and run pre-commit
+      - run: |
+          uv run pre-commit install
+          uv run pre-commit run --all-files
+
+  pytest:
+    name: Pytest ${{ matrix.config.name }}
+    runs-on: ${{ matrix.config.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12"]
+        config:
+          - { name: "Linux", os: ubuntu-latest }
+          - { name: "MacOSX", os: macos-latest }
+          - { name: "Windows", os: windows-latest }
+
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.8.12"
+          enable-cache: true
+      - name: Install and Run Tests
+        run: |
+          uv sync --dev
+          uv pip install -r tests/requirements.txt
+          uv run pytest -s ./tests
+
+  test-npm-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set Up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Build Vue Components
+        run: |
+          cd vue-components
+          npm i
+          npm run build
+
+  release:
+    needs: [pre-commit, pytest, test-npm-build]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+      contents: write # IMPORTANT: mandatory for making GitHub Releases
+      attestations: write # IMPORTANT: mandatory to attest build provenance
+    if: github.event_name == 'push'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set Up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Build Vue Components
+        run: |
+          cd vue-components
+          npm i
+          npm run build
+
+      - name: Python Semantic Release
+        id: release
+        uses: python-semantic-release/python-semantic-release@v10.5.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Generate artifact attestation for sdist and wheel
+        if: steps.release.outputs.released == 'true'
+        uses: actions/attest-build-provenance@v4.1.0
+        with:
+          subject-path: "dist/*"
+
+      # https://docs.pypi.org/trusted-publishers/using-a-publisher/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        if: steps.release.outputs.released == 'true'

trame_code-1.1.0/.gitignore

@@ -0,0 +1,27 @@
+.DS_Store
+node_modules
+.venv
+build
+
+# local env files
+.env.local
+.env.*.local
+
+# Log files
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+__pycache__
+*egg-info
+*pyc

trame_code-1.1.0/.pre-commit-config.yaml

@@ -0,0 +1,68 @@
+ci:
+  autoupdate_commit_msg: "chore: update pre-commit hooks"
+  autofix_commit_msg: "style: pre-commit fixes"
+
+exclude: ^.cruft.json|.copier-answers.yml$|uv\.lock$
+
+repos:
+  - 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.15.10"
+    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: https://github.com/abravalheri/validate-pyproject
+    rev: "v0.25"
+    hooks:
+      - id: validate-pyproject
+        additional_dependencies:
+          - validate-pyproject[all]
+          - validate-pyproject-schema-store
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: "0.31.0"
+    hooks:
+      - id: check-dependabot
+      - id: check-github-workflows
+      - id: check-readthedocs

trame_code-1.1.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+<!--next-version-placeholder-->
+
+## v1.0.2 (2025-01-07)
+
+### Fix
+
+- Update vue2 example to use vue2 client type
+  ([`34b443d`](https://github.com/Kitware/trame-code/commit/34b443d4b02328db155a4e152516d312dbfa7090))
+- Initial value for vue2
+  ([`b356e66`](https://github.com/Kitware/trame-code/commit/b356e66608b7b0655bffa4022c8f9815ceffcdbf))
+- Bring back vue2 support
+  ([`d9dc6f8`](https://github.com/Kitware/trame-code/commit/d9dc6f8fe0d393e596a0eeb4a0d20d32e5aa6681))
+- Update to use modelValue for vue3
+  ([`4274d8f`](https://github.com/Kitware/trame-code/commit/4274d8f8221c2bc2f3052900186444ca8dab6af0))
+
+### Documentation
+
+- Remove value from python wrapper
+  ([`9172e3b`](https://github.com/Kitware/trame-code/commit/9172e3b87a3959dee4df5bcbbf912576a5bbd459))
+- Update README.rst
+  ([`adc54bb`](https://github.com/Kitware/trame-code/commit/adc54bb796288d91b8b9d89c8140b24e7b372e1f))
+
+## v1.0.1 (2023-08-16)
+
+### Fix
+
+- **docs:** Improve API
+  ([`e125a5b`](https://github.com/Kitware/trame-code/commit/e125a5b03ea7518329adadb082fc4f142fd6f28e))
+
+### Documentation
+
+- **layout:** Use automaticLayout option
+  ([`c416d98`](https://github.com/Kitware/trame-code/commit/c416d98d2827e06d0a281733186016d6dbee98ca))
+- **example:** Cleanup of textmate
+  ([`d2e3eb3`](https://github.com/Kitware/trame-code/commit/d2e3eb322bef5574b2ae5ab0971d43c4a8335cd7))
+
+## v1.0.0 (2023-04-19)
+
+### Feature
+
+- **release:** Official release
+  ([`080923c`](https://github.com/Kitware/trame-code/commit/080923c5ad7343dac65e192902947ed08f761f57))
+
+### Breaking
+
+- Just making that library official now that it vue2/3 compatible
+  ([`080923c`](https://github.com/Kitware/trame-code/commit/080923c5ad7343dac65e192902947ed08f761f57))
+
+## v0.1.0 (2023-04-18)
+
+### Feature
+
+- **textmate:** Handle textmate format
+  ([`83cfb97`](https://github.com/Kitware/trame-code/commit/83cfb97110296afa5fbfd31a2d66a4c8dc9810d1))
+- **vue23:** Working for both vue client
+  ([`13b5a92`](https://github.com/Kitware/trame-code/commit/13b5a92851a3f73f6020626547e63a7c4887cead))
+- Initial VS code editor
+  ([`831f907`](https://github.com/Kitware/trame-code/commit/831f90763d6a37088a648b2948f7f4b80b6c81aa))
+
+### Fix
+
+- **version:** Add **version**
+  ([`efac4ab`](https://github.com/Kitware/trame-code/commit/efac4abe7c61c0ce562e88c54461d3a19b1e553d))
+- **options:** Fix setting the language and theme
+  ([`4ae0c42`](https://github.com/Kitware/trame-code/commit/4ae0c42055df982181453371ae76dd9e5677b451))

trame_code-1.1.0/CONTRIBUTING.rst

@@ -0,0 +1,19 @@
+==========================
+Contributing to trame-code
+==========================
+
+#. Clone the repository using ``git clone``
+#. Install pre-commit via ``pip install pre-commit``
+#. Run ``pre-commit install`` to set up pre-commit hooks
+#. Make changes to the code, and commit your changes to a separate branch
+#. 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 ``black`` issues is by installing black (``pip install black``) and running the ``black`` command at the root of your repository.
+#. Sometimes, ``black`` and ``flake8`` do not agree. Add options to your ``.flake8`` file to fix these things. See the `flake8 configuration docs <https://flake8.pycqa.org/en/latest/user/configuration.html>`_ for more details.
+#. 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.

{trame-code-1.0.1/trame_code.egg-info → trame_code-1.1.0}/PKG-INFO

@@ -1,25 +1,32 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: trame-code
-Version: 1.0.1
+Version: 1.1.0
 Summary: Widget for Monaco VS code editor for trame
 Author: Kitware Inc.
 License: MIT License
-Keywords: Python,Interactive,Web,Application,Framework
+License-File: LICENSE
+Keywords: Application,Framework,Interactive,Python,Web
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Web Environment
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: trame-client
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest>=6; extra == 'dev'
 Description-Content-Type: text/x-rst
-License-File: LICENSE
 
-==========
-trame-code
-==========
+.. |pypi_download| image:: https://img.shields.io/pypi/dm/trame-code
+
+==============================
+trame-code |pypi_download|
+==============================
 
 Widget for Monaco VS code editor for trame
 
@@ -47,3 +54,15 @@ Install the python library
 .. code-block:: console
 
     pip install -e .
+
+
+JavaScript dependency
+-----------------------------------------------------------
+
+This Python package bundle the following set of libraries:
+
+* ``monaco-editor@0.37.1``
+* ``vscode-oniguruma@1.7.0``
+* ``vscode-textmate@9.0.0``
+
+If you would like us to upgrade any of those dependencies, `please reach out <https://www.kitware.com/trame/>`_.

trame_code-1.1.0/README.rst

@@ -0,0 +1,44 @@
+.. |pypi_download| image:: https://img.shields.io/pypi/dm/trame-code
+
+==============================
+trame-code |pypi_download|
+==============================
+
+Widget for Monaco VS code editor for trame
+
+
+License
+-----------------------------------------------------------
+
+This library is distributed under the MIT License (Same as monaco/vscode-editor)
+
+
+Development
+-----------------------------------------------------------
+
+Build and install the Vue components
+
+.. code-block:: console
+
+    cd vue-components
+    npm i
+    npm run build
+    cd -
+
+Install the python library
+
+.. code-block:: console
+
+    pip install -e .
+
+
+JavaScript dependency
+-----------------------------------------------------------
+
+This Python package bundle the following set of libraries:
+
+* ``monaco-editor@0.37.1``
+* ``vscode-oniguruma@1.7.0``
+* ``vscode-textmate@9.0.0``
+
+If you would like us to upgrade any of those dependencies, `please reach out <https://www.kitware.com/trame/>`_.

trame_code-1.1.0/example/language-features/app.py

@@ -0,0 +1,99 @@
+"""Editor language features: completion + hover backed by a Python callback.
+
+The ``completion`` and ``hover`` props on ``code.Editor`` each take a callable
+that receives ``(code, line, column)`` and returns results. Here both are backed
+by jedi, giving live Python completion and docstring-on-hover entirely
+in-process, with no client-side JavaScript.
+
+The contract:
+
+* completion returns a list of items, each a dict with keys ``label`` (required),
+  ``kind``, ``detail``, ``documentation``, ``insertText``.
+* hover returns a markdown string, a list of markdown strings, or
+  ``{"contents": [...]}`` (or ``None`` for no hover).
+* positions are passed as ``line`` (1-based) and ``column`` (0-based), matching
+  jedi's API directly.
+
+Run with::
+
+    pip install trame trame-vuetify trame-code jedi
+    python app.py
+"""
+
+import jedi
+from trame.app import TrameApp
+from trame.ui.vuetify3 import SinglePageLayout
+
+from trame.widgets import code
+from trame.widgets import vuetify3 as v3
+
+INITIAL_CODE = '''import math
+
+
+def circle_area(radius):
+    """Return the area of a circle with the given radius."""
+    return math.pi * radius**2
+
+
+# Type "math." below, or hover a name, to see completion and docstrings.
+math.
+'''
+
+
+class PyCodeEditor(TrameApp):
+    def __init__(self, server=None):
+        super().__init__(server)
+        self._build_ui()
+
+    def _build_ui(self):
+        self.state.trame__title = "PyEditor"
+        with SinglePageLayout(self.server) as self.ui:
+            self.ui.title.set_text("Editor language features (jedi)")
+            with self.ui.content:
+                with v3.VContainer(fluid=True, classes="fill-height pa-0"):
+                    code.Editor(
+                        v_model=("editor_code", INITIAL_CODE),
+                        language="python",
+                        theme="vs",
+                        style="width: 100%; height: 100%;",
+                        completion=self.on_completion,
+                        hover=self.on_hover,
+                    )
+
+    def on_completion(self, code_text, line, column):
+        """Completion items for (code, line, column): line 1-based, column 0-based."""
+        try:
+            completions = jedi.Script(code=code_text).complete(line, column)
+        except Exception:
+            return []
+        return [
+            {
+                "label": c.name,
+                "kind": c.type,
+                "detail": (c.description or "")[:80],
+            }
+            for c in completions[:200]
+        ]
+
+    def on_hover(self, code_text, line, column):
+        """Hover markdown (signature + docstring) for the symbol at the cursor."""
+        try:
+            definitions = jedi.Script(code=code_text).help(line, column)
+        except Exception:
+            return None
+        if not definitions:
+            return None
+        definition = definitions[0]
+        contents = []
+        signatures = [s.to_string() for s in definition.get_signatures()]
+        if signatures:
+            contents.append("```python\n" + "\n".join(signatures) + "\n```")
+        doc = definition.docstring(raw=True) or ""
+        if doc:
+            contents.append(doc)
+        return {"contents": contents} if contents else None
+
+
+if __name__ == "__main__":
+    app = PyCodeEditor()
+    app.server.start()

trame_code-1.1.0/example/language-features/requirements.txt

@@ -0,0 +1,4 @@
+jedi
+trame
+trame-code
+trame-vuetify

trame_code-1.1.0/example/live-state/app.py

@@ -0,0 +1,129 @@
+"""Editor language features: completion from live in-process state.
+
+This example shows the capability that distinguishes a callback-backed provider
+from a language server: the suggestions come from a live Python object in the
+running process, not from source text or type stubs. A language server cannot
+offer these names, because they exist only at runtime.
+
+Here the editor completes the keys of an in-memory ``DATASET`` when the cursor
+is inside a ``dataset["..."]`` subscript, annotating each with the live value's
+type and length. Swap ``DATASET`` for a loaded data file, a database schema, or
+any live object and the same handler surfaces those names into the editor.
+
+The contract (shared with the language-features example):
+
+* completion returns a list of items, each a dict with key ``label`` (required)
+  and optional ``kind``, ``detail``, ``documentation``, ``insertText``.
+* positions are passed as ``line`` (1-based) and ``column`` (0-based).
+
+Run with::
+
+    pip install trame trame-vuetify trame-code
+    python app.py
+"""
+
+import re
+
+from trame.app import TrameApp
+from trame.ui.vuetify3 import SinglePageLayout
+
+from trame.widgets import code
+from trame.widgets import vuetify3 as vuetify
+
+# Stand-in for state that exists only at runtime (a loaded dataset, a live
+# object graph, a fetched schema...). None of these names appear in the source.
+DATASET = {
+    "pressure": [0.0] * 1000,
+    "density": [0.0] * 1000,
+    "temperature": [0.0] * 1000,
+    "velocity": [(0.0, 0.0, 0.0)] * 1000,
+    "time_steps": list(range(50)),
+}
+
+# Match an unclosed string subscript at the cursor:  dataset["pre
+_SUBSCRIPT_RE = re.compile(r"""\[\s*["']([^"']*)$""")
+
+INITIAL_CODE = """# Live-state completion demo
+#
+# 1. Put the cursor between the empty quotes on the last line:  dataset[""]
+# 2. Type a letter (p, d, t, or v). Suggestions appear automatically.
+# 3. The keys are read live from the in-memory DATASET object
+#    (pressure, density, temperature, velocity, time_steps),
+#    each shown with its Python type and length.
+#
+# A language server cannot offer these: they exist only at runtime.
+
+field = dataset[""]
+"""
+
+
+def _describe(value):
+    """A short, live description of a value: type plus length when available."""
+    type_name = type(value).__name__
+    try:
+        return f"{type_name}, len {len(value)}"
+    except TypeError:
+        return type_name
+
+
+class LiveStateEditor(TrameApp):
+    def __init__(self, server=None):
+        super().__init__(server)
+        self._build_ui()
+
+    def _build_ui(self):
+        self.state.trame__title = "Live-state completion"
+        with SinglePageLayout(self.server) as self.ui:
+            self.ui.title.set_text("Live-state completion")
+            with self.ui.content:
+                with vuetify.VContainer(fluid=True, classes="fill-height pa-0"):
+                    code.Editor(
+                        v_model=("live_code", INITIAL_CODE),
+                        language="python",
+                        theme="vs",
+                        completion=self.live_complete,
+                        # open the list as soon as the key string is entered
+                        completion_trigger_characters=(
+                            "completion_triggers",
+                            ['"', "'", "["],
+                        ),
+                        # dict-key completion happens inside a string literal,
+                        # where Monaco suppresses suggestions by default; enable
+                        # them there, and drop document-word noise.
+                        options=(
+                            "live_editor_options",
+                            {
+                                "quickSuggestions": {
+                                    "other": True,
+                                    "comments": False,
+                                    "strings": True,
+                                },
+                                "wordBasedSuggestions": False,
+                                "minimap": {"enabled": False},
+                            },
+                        ),
+                        style="width: 100%; height: 100%;",
+                    )
+
+    def live_complete(self, code_text, line, column):
+        """Complete DATASET keys when the cursor is inside a string subscript."""
+        lines = code_text.split("\n")
+        if line < 1 or line > len(lines):
+            return []
+        prefix = lines[line - 1][:column]
+
+        match = _SUBSCRIPT_RE.search(prefix)
+        if not match:
+            return []  # not inside a key subscript -> defer to others
+
+        stub = match.group(1)
+        return [
+            {"label": key, "kind": "field", "detail": _describe(value)}
+            for key, value in DATASET.items()
+            if key.startswith(stub)
+        ]
+
+
+if __name__ == "__main__":
+    app = LiveStateEditor()
+    app.server.start()

trame_code-1.1.0/example/live-state/requirements.txt

@@ -0,0 +1,3 @@
+trame
+trame-code
+trame-vuetify

trame_code-1.1.0/example/read-only/requirements.txt

@@ -0,0 +1,2 @@
+trame
+trame-code