DOCSEARCHbyAlgolia
Submit Docs

euporie

repository·dev·Indexed 25 days ago

https://github.com/joouha/euporie

A suite of terminal-based Jupyter applications. The euporie-core library provides the foundation framework, including Jupyter kernel integration, rich-output rendering, and a core application framework. It utilizes apptk for extending prompt_toolkit and supports features such as autosave, custom key bindings, and popup notifications.

Tokens
36.2K
Snippets
92
Records
305
Agent score
79%

What's inside euporie

  1. Overview of euporie-core features

    dev

    euporie-core is a shared foundation library for terminal Jupyter applications. Key capabilities include:

    • Application framework: BaseApp class for application loops, configuration, key bindings, and command palettes.
    • Jupyter integration: Kernel discovery, lifecycle management, and message handling via jupyter-client, plus ipywidgets rendering.
    • Notebook handling: Support for .ipynb and Jupytext-compatible formats via nbformat and jupytext.
    • Rich rendering: Support for Markdown, LaTeX, HTML, SVG, PDF, tables, and terminal graphics (Sixel, iTerm, Kitty).
    • LSP support: Language Server Protocol client for completion, diagnostics, and formatting.
    • Configuration: Settings managed via CLI flags, config files (pyproject.toml-style), and environment variables.
    • Filesystem abstraction: Integration with fsspec and universal-pathlib for local, HTTP, and in-memory paths.
    • UI Components: Reusable widgets like dialogs, menus, toolbars, pagers, search bars, and cell-output containers.

  2. Overview of euporie-console features

    dev

    euporie-console is a terminal-based Jupyter REPL that renders rich kernel output directly in the terminal.

    Key features include:

    • Rich output rendering: Images, Markdown, LaTeX, HTML, tables, and PDFs.
    • Interactive widgets: Supports ipywidgets in the terminal.
    • Editing & Completion: Multi-line editing with kernel-aware completeness, tab-completion, and line suggestions.
    • Session Management: Export current sessions as .ipynb notebooks or hand them off to euporie-notebook.
    • Customization: Supports Vim, Emacs, Helix, and Micro-style key bindings.
    • Kernel Integration: Connect to existing kernels via connection files and access history sourced from the kernel.

  3. Overview of Euporie libraries

    dev

    Euporie includes two core libraries for developers building terminal applications:

    • euporie-core: The foundational framework used by all Euporie applications. It provides the shared application framework, kernel client, notebook handling, and rich-output rendering capabilities.
    • apptk: An enhancement layer built on top of prompt_toolkit. It provides advanced terminal UI features such as docking, terminal graphics, an enriched style system, and a centralized command registry.

  4. Overview of Euporie applications

    dev

    Euporie provides a suite of terminal applications for interacting with Jupyter notebooks and kernels:

    • Euporie Notebook: An interactive TUI (Terminal User Interface) Jupyter Notebook editor. It supports viewing, editing, and running notebooks while utilizing Jupyter's rich output system to render various media types in the terminal.
    • Euporie Console: A terminal frontend for Jupyter kernels. It uses euporie's rich display system and supports interactive ipywidgets. Console session histories can be converted into notebooks.
    • Euporie Preview: A non-interactive notebook renderer. It allows you to preview notebooks in the terminal, print output to stdout, pipe to a pager, save to a file, or run notebooks before rendering.
    • Euporie Hub: A multi-user SSH server (similar to JupyterHub) that allows multiple users to share server resources. Users can be configured to launch the notebook editor or other applications.

  5. Use the euporie CLI launcher

    dev
    The euporie command acts as a unified entry point (launcher) for various euporie applications. It is included in the euporie metapackage. You can use it to start different euporie apps such as euporie-console, euporie-notebook, euporie-preview, and euporie-hub through a single command.

  6. Explore euporie features via the Gallery

    dev

    The euporie gallery provides visual demonstrations of the project's capabilities across different versions. Key features showcased include:

    Modern Features (v3.x.x):

    • Custom tab layouts and command bars.
    • Variable viewer and Mermaid diagram support.
    • Selecting and copying text from cell outputs.
    • Clickable OSC 8 hyperlinks.
    • Integrated terminal support.
    • TOML-based configuration.
    • Custom key bindings and background patterns.

    Legacy Features (v2.x.x, v1.x.x, v0.x.x):

    • Ipywidget support and Markdown cell rendering.
    • Command palette and search functionality.
    • Various color schemes (Dark, Light, Black, White, Inverse, Custom).
    • Side-by-side notebook display and tiling.
    • Tab completion and contextual help.
    • LaTeX formulae rendering with SymPy.
    • Multi-indexed dataframe display and Unicode image rendering.

  7. Understand the Euporie package structure

    dev

    Euporie is organized as a uv workspace monorepo. It consists of a top-level euporie metapackage (the launcher) and several independent packages located in packages/. All packages share a single version number.

    Package Overview:

    • apptk: Extensions for prompt_toolkit using modshim.
    • euporie-core: The shared application framework, including the BaseApp class, kernel client, configuration system, command registry, and widgets.
    • euporie-console: Interactive REPL application.
    • euporie-notebook: Notebook editor application.
    • euporie-preview: Non-interactive preview application.
    • euporie-hub: SSH server for hosting applications.
    • euporie: The main launcher entry-point that dispatches to sub-apps based on command-line arguments.
    euporie/
├── packages/
│   ├── apptk/                 # prompt_toolkit extensions
│   ├── euporie-core/          # shared application framework
│   ├── euporie-console/       # interactive REPL app
│   ├── euporie-notebook/      # notebook editor app
│   ├── euporie-preview/      # non-interactive preview app
│   └── euporie-hub/           # SSH server hosting the apps
└── src/euporie/launch/        # the `euporie` launcher entry-point

  9. Access notebooks in cloud storage

    dev

    Euporie supports cloud storage via fsspec plugins. To use these, you must install the corresponding provider package. Authentication is handled via standard environment variables for each provider (e.g., AWS_PROFILE or AWS_ACCESS_KEY_ID for S3).

    Supported providers:

    • S3: Install s3fs and use s3://bucket/key.ipynb.
    • Google Cloud Storage: Install gcsfs and use gs://bucket/key.ipynb.
    • Azure Blob Storage: Install adlfs and use az://container/key.ipynb.
    • GitHub: Use the built-in fsspec plugin with the format github://user:repo@branch/path.ipynb.

  11. Install ipywidgets for terminal use

    dev

    To use interactive widgets in the terminal via euporie, you must install ipywidgets within the same environment where your Jupyter kernel is running. You do not need to install anything in the euporie environment itself, as euporie renders the widgets based on the messages emitted by the kernel.

    $ pip install ipywidgets

  12. Follow Euporie Python coding conventions

    dev

    When contributing to Euporie, adhere to these coding standards:

    Imports

    • Every file must start with from __future__ import annotations.
    • Use absolute imports.
    • No wildcard imports (from module import *).
    • Crucial: Import from apptk instead of prompt_toolkit when using shimmed functionality.
    • Order imports with blank lines: 1. Future imports, 2. Standard library, 3. Third-party, 4. Local imports.

    Formatting

    • Indentation: 4 spaces, no tabs.
    • Max line length: 88 characters.
    • Use ruff format and ruff check --fix before committing.

    Naming

    • snake_case: functions, methods, variables.
    • PascalCase: classes.
    • UPPER_SNAKE_CASE: constants.
    • _prefix: private members.
    • _T, _U, etc.: type variables.

    Type Annotations

    • Always use type annotations for function signatures.
    • Use built-in generics (e.g., list[str], dict[str, int]).
    • Use | for unions (e.g., str | None).
    • Use collections.abc for abstract types (e.g., Sequence, Callable).
    • Use TYPE_CHECKING blocks for import-only types to prevent circular imports.