notebookx-py 0.1.4__cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

notebookx/__init__.py

@@ -0,0 +1,45 @@
+"""notebookx - Fast, lightweight notebook conversion library.
+
+This library provides a unified representation for Jupyter notebooks
+and supports conversion between different notebook formats.
+
+Example:
+    >>> from notebookx import Notebook, Format
+    >>>
+    >>> # Load a notebook
+    >>> nb = Notebook.from_file("example.ipynb")
+    >>>
+    >>> # Convert to percent format
+    >>> nb.to_file("example.pct.py")
+    >>>
+    >>> # Clean a notebook
+    >>> clean_nb = nb.clean(remove_outputs=True)
+"""
+
+from notebookx._notebookx import (
+    Notebook,
+    Format,
+    CleanOptions,
+    convert,
+    clean_notebook,
+    run_cli,
+    NotebookError,
+    format_from_extension,
+    format_from_path,
+    format_extension,
+)
+
+__all__ = [
+    "Notebook",
+    "Format",
+    "CleanOptions",
+    "convert",
+    "clean_notebook",
+    "run_cli",
+    "NotebookError",
+    "format_from_extension",
+    "format_from_path",
+    "format_extension",
+]
+
+__version__ = "0.1.0"

notebookx/__init__.pyi

@@ -0,0 +1,293 @@
+"""Type stubs for notebookx."""
+
+from enum import Enum
+from typing import Optional, List
+
+class Format(Enum):
+    """Supported notebook formats."""
+    Ipynb = ...
+    Percent = ...
+
+
+def format_from_extension(ext: str) -> Optional[Format]:
+    """Infer the format from a file extension.
+
+    Args:
+        ext: File extension (e.g., "ipynb", "pct.py"). Leading dot is optional.
+
+    Returns:
+        The inferred format, or None if the extension is not recognized.
+
+    Example:
+        >>> format_from_extension("ipynb")
+        Format.Ipynb
+        >>> format_from_extension(".pct.py")
+        Format.Percent
+    """
+    ...
+
+
+def format_from_path(path: str) -> Optional[Format]:
+    """Infer the format from a file path.
+
+    Handles compound extensions like `.pct.py`.
+
+    Args:
+        path: Path to a notebook file.
+
+    Returns:
+        The inferred format, or None if the format cannot be determined.
+
+    Example:
+        >>> format_from_path("notebook.ipynb")
+        Format.Ipynb
+        >>> format_from_path("/path/to/file.pct.py")
+        Format.Percent
+    """
+    ...
+
+
+def format_extension(format: Format) -> str:
+    """Get the canonical file extension for a format.
+
+    Args:
+        format: The notebook format.
+
+    Returns:
+        The file extension (e.g., "ipynb", "pct.py").
+
+    Example:
+        >>> format_extension(Format.Ipynb)
+        'ipynb'
+        >>> format_extension(Format.Percent)
+        'pct.py'
+    """
+    ...
+
+class CleanOptions:
+    """Options for cleaning a notebook."""
+
+    remove_outputs: bool
+    remove_execution_counts: bool
+    remove_cell_metadata: bool
+    remove_notebook_metadata: bool
+    remove_kernel_info: bool
+    preserve_cell_ids: bool
+    remove_output_metadata: bool
+    remove_output_execution_counts: bool
+    allowed_cell_metadata_keys: Optional[List[str]]
+    allowed_notebook_metadata_keys: Optional[List[str]]
+
+    def __init__(
+        self,
+        remove_outputs: bool = False,
+        remove_execution_counts: bool = False,
+        remove_cell_metadata: bool = False,
+        remove_notebook_metadata: bool = False,
+        remove_kernel_info: bool = False,
+        preserve_cell_ids: bool = False,
+        remove_output_metadata: bool = False,
+        remove_output_execution_counts: bool = False,
+        allowed_cell_metadata_keys: Optional[List[str]] = None,
+        allowed_notebook_metadata_keys: Optional[List[str]] = None,
+    ) -> None: ...
+
+    @staticmethod
+    def for_vcs() -> CleanOptions:
+        """Create options for version control (removes cell metadata, execution counts, and output metadata/execution counts)."""
+        ...
+
+    @staticmethod
+    def strip_all() -> CleanOptions:
+        """Create options that strip all metadata and outputs."""
+        ...
+
+class Notebook:
+    """A Jupyter notebook."""
+
+    @property
+    def code_cell_count(self) -> int:
+        """Get the number of code cells."""
+        ...
+
+    @property
+    def markdown_cell_count(self) -> int:
+        """Get the number of markdown cells."""
+        ...
+
+    @property
+    def raw_cell_count(self) -> int:
+        """Get the number of raw cells."""
+        ...
+
+    @property
+    def nbformat(self) -> int:
+        """Get the nbformat version."""
+        ...
+
+    @property
+    def nbformat_minor(self) -> int:
+        """Get the nbformat minor version."""
+        ...
+
+    def __init__(self) -> None:
+        """Create a new empty notebook."""
+        ...
+
+    @staticmethod
+    def from_file(path: str, format: Optional[Format] = None) -> Notebook:
+        """Load a notebook from a file.
+
+        Args:
+            path: Path to the notebook file.
+            format: Optional format. If not specified, inferred from extension.
+
+        Returns:
+            The loaded notebook.
+
+        Raises:
+            ValueError: If the file cannot be parsed.
+            IOError: If the file cannot be read.
+        """
+        ...
+
+    @staticmethod
+    def from_string(content: str, format: Format) -> Notebook:
+        """Load a notebook from a string.
+
+        Args:
+            content: The notebook content as a string.
+            format: The format of the content.
+
+        Returns:
+            The loaded notebook.
+
+        Raises:
+            ValueError: If the content cannot be parsed.
+        """
+        ...
+
+    def to_file(self, path: str, format: Optional[Format] = None) -> None:
+        """Save the notebook to a file.
+
+        Args:
+            path: Path to save the notebook to.
+            format: Optional format. If not specified, inferred from extension.
+
+        Raises:
+            ValueError: If the notebook cannot be serialized.
+            IOError: If the file cannot be written.
+        """
+        ...
+
+    def to_string(self, format: Format) -> str:
+        """Serialize the notebook to a string.
+
+        Args:
+            format: The format to serialize to.
+
+        Returns:
+            The notebook as a string.
+
+        Raises:
+            ValueError: If the notebook cannot be serialized.
+        """
+        ...
+
+    def clean(self, options: Optional[CleanOptions] = None) -> Notebook:
+        """Clean the notebook according to the specified options.
+
+        This returns a new notebook with the requested content removed.
+        The original notebook is not modified.
+
+        Args:
+            options: Cleaning options. If not specified, uses default options.
+
+        Returns:
+            A new cleaned notebook.
+        """
+        ...
+
+    def is_empty(self) -> bool:
+        """Check if the notebook is empty."""
+        ...
+
+    def __len__(self) -> int:
+        """Get the number of cells in the notebook."""
+        ...
+
+    def __repr__(self) -> str: ...
+
+class NotebookError(Exception):
+    """Custom exception for notebook errors."""
+    ...
+
+def convert(
+    input_path: str,
+    output_path: str,
+    from_fmt: Optional[Format] = None,
+    to_fmt: Optional[Format] = None,
+) -> None:
+    """Convert a notebook between formats.
+
+    Args:
+        input_path: Path to the input notebook.
+        output_path: Path to save the converted notebook.
+        from_fmt: Optional input format. If not specified, inferred from extension.
+        to_fmt: Optional output format. If not specified, inferred from extension.
+
+    Raises:
+        ValueError: If formats cannot be inferred or conversion fails.
+        IOError: If files cannot be read or written.
+    """
+    ...
+
+def clean_notebook(
+    input_path: str,
+    output_path: Optional[str] = None,
+    remove_outputs: bool = False,
+    remove_execution_counts: bool = False,
+    remove_cell_metadata: bool = False,
+    remove_notebook_metadata: bool = False,
+    remove_kernel_info: bool = False,
+    preserve_cell_ids: bool = False,
+    remove_output_metadata: bool = False,
+    remove_output_execution_counts: bool = False,
+) -> None:
+    """Clean a notebook file.
+
+    Args:
+        input_path: Path to the input notebook.
+        output_path: Optional path to save the cleaned notebook.
+                     If not specified, cleans in place.
+        remove_outputs: Remove all outputs from code cells.
+        remove_execution_counts: Remove execution counts from code cells.
+        remove_cell_metadata: Remove cell-level metadata.
+        remove_notebook_metadata: Remove notebook-level metadata.
+        remove_kernel_info: Remove kernel specification.
+        preserve_cell_ids: Preserve cell IDs.
+        remove_output_metadata: Remove metadata from outputs (ExecuteResult, DisplayData).
+        remove_output_execution_counts: Remove execution counts from output results.
+
+    Raises:
+        ValueError: If the file cannot be parsed.
+        IOError: If files cannot be read or written.
+    """
+    ...
+
+def run_cli(args: List[str]) -> int:
+    """Run the nbx CLI with the given arguments.
+
+    This function runs the Rust CLI directly, providing the same functionality
+    as the standalone `nbx` binary.
+
+    Args:
+        args: Command-line arguments (including the program name as first element).
+
+    Returns:
+        Exit code (0 for success, non-zero for errors).
+    """
+    ...
+
+__version__: str
+__all__: List[str]

notebookx/cli.py

@@ -0,0 +1,18 @@
+"""Command-line interface for notebookx.
+
+This module provides the `nbx` command when notebookx is installed via pip.
+It's a thin wrapper that calls the Rust CLI implementation directly.
+"""
+
+import sys
+
+from notebookx._notebookx import run_cli
+
+
+def cli_main():
+    """Entry point that runs the Rust CLI and exits with its return code."""
+    sys.exit(run_cli(sys.argv))
+
+
+if __name__ == "__main__":
+    cli_main()

notebookx_py-0.1.4.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: notebookx-py
+Version: 0.1.4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Fast, lightweight notebook conversion library
+Keywords: jupyter,notebook,conversion,ipynb
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/lukastk/notebookx
+Project-URL: Repository, https://github.com/lukastk/notebookx
+
+# notebookx
+
+A fast, lightweight notebook conversion library written in Rust with Python bindings.
+
+notebookx is a Rust-based alternative to Python's nbconvert, providing fast notebook conversion between formats like `.ipynb` and percent format (`.pct.py`).
+
+## Features
+
+- **Fast**: Written in Rust for maximum performance
+- **Multiple interfaces**: Use as a Rust library, CLI tool (`nbx`), or Python package
+- **Format conversion**: Convert between ipynb and percent format
+- **Notebook cleaning**: Strip outputs, execution counts, and metadata for version control
+- **Cross-platform**: Works on Linux, macOS, and Windows
+
+## Installation
+
+### Python
+
+```bash
+pip install notebookx-py
+```
+
+### Rust
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+notebookx = "0.1"
+```
+
+### CLI
+
+```bash
+cargo install notebookx --features cli
+```
+
+## Usage
+
+### Python
+
+```python
+from notebookx import Notebook, Format, CleanOptions
+
+# Load a notebook
+nb = Notebook.from_file("example.ipynb")
+
+# Convert to percent format
+nb.to_file("example.pct.py")
+
+# Or get as string
+percent_content = nb.to_string(Format.Percent)
+
+# Clean notebook for version control
+clean_nb = nb.clean(CleanOptions(
+    remove_outputs=True,
+    remove_execution_counts=True,
+))
+clean_nb.to_file("clean.ipynb")
+
+# Convenience functions
+from notebookx import convert, clean_notebook
+
+convert("input.ipynb", "output.pct.py")
+clean_notebook("notebook.ipynb", remove_outputs=True)
+```
+
+### CLI (`nbx`)
+
+```bash
+# Convert ipynb to percent format
+nbx convert notebook.ipynb --to notebook.pct.py
+
+# Convert percent to ipynb
+nbx convert notebook.pct.py --to notebook.ipynb
+
+# Clean a notebook (remove outputs)
+nbx clean notebook.ipynb --output clean.ipynb --remove-outputs
+
+# Clean in place
+nbx clean notebook.ipynb --in-place --remove-outputs --remove-execution-counts
+
+# Use stdin/stdout
+cat notebook.ipynb | nbx convert - --from-fmt ipynb --to - --to-fmt percent
+```
+
+### Rust
+
+```rust
+use notebookx::{Notebook, NotebookFormat, CleanOptions};
+
+// Parse from file
+let content = std::fs::read_to_string("example.ipynb")?;
+let notebook = NotebookFormat::Ipynb.parse(&content)?;
+
+// Convert to percent format
+let percent = NotebookFormat::Percent.serialize(&notebook)?;
+
+// Clean notebook
+let options = CleanOptions {
+    remove_outputs: true,
+    remove_execution_counts: true,
+    ..Default::default()
+};
+let clean = notebook.clean(&options);
+
+// Save to file
+let output = NotebookFormat::Ipynb.serialize(&clean)?;
+std::fs::write("clean.ipynb", output)?;
+```
+
+## Supported Formats
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| ipynb | `.ipynb` | Standard Jupyter notebook format (JSON) |
+| percent | `.pct.py` | Percent format used by Jupytext, VSCode, etc. |
+
+## Clean Options
+
+When cleaning notebooks, you can control what gets removed:
+
+| Option | Description |
+|--------|-------------|
+| `remove_outputs` | Remove all cell outputs |
+| `remove_execution_counts` | Reset execution counts to null |
+| `remove_cell_metadata` | Remove cell-level metadata |
+| `remove_notebook_metadata` | Remove notebook-level metadata |
+| `remove_kernel_info` | Remove kernel specification |
+| `preserve_cell_ids` | Keep cell IDs (default: regenerate) |
+| `remove_output_metadata` | Remove metadata from outputs |
+| `remove_output_execution_counts` | Remove execution counts from outputs |
+
+### Presets
+
+**Python:**
+```python
+# For version control (removes cell metadata, execution counts, and output metadata)
+# Preserves outputs so rendered content remains visible
+options = CleanOptions.for_vcs()
+
+# Strip everything (including outputs)
+options = CleanOptions.strip_all()
+```
+
+## CLI Reference
+
+### `nbx convert`
+
+Convert notebooks between formats.
+
+```
+nbx convert <INPUT> --to <OUTPUT> [OPTIONS]
+
+Options:
+  --from-fmt <FORMAT>  Input format (ipynb, percent). Inferred from extension if not specified.
+  --to-fmt <FORMAT>    Output format (ipynb, percent). Inferred from extension if not specified.
+  -h, --help           Print help
+```
+
+### `nbx clean`
+
+Clean notebooks by removing outputs and metadata.
+
+```
+nbx clean <INPUT> [OPTIONS]
+
+Options:
+  -o, --output <FILE>           Output file (default: stdout)
+  -i, --in-place                Modify file in place
+  -O, --remove-outputs          Remove all outputs
+  -e, --remove-execution-counts Remove execution counts
+  --remove-cell-metadata        Remove cell metadata
+  --remove-notebook-metadata    Remove notebook metadata
+  --remove-kernel-info          Remove kernel specification
+  -h, --help                    Print help
+```
+
+## Development
+
+### Building from source
+
+```bash
+# Clone the repository
+git clone https://github.com/lukastk/notebookx.git
+cd notebookx
+
+# Build Rust library and CLI
+cargo build --release
+
+# Build Python package
+pip install maturin
+maturin develop
+```
+
+### Running tests
+
+```bash
+# Rust tests
+cargo test --workspace
+
+# Python tests
+pytest tests/python
+```
+
+## License
+
+MIT
+
+## Acknowledgements
+
+Example notebooks in `nb_format_examples/` are from the [Jupytext demo](https://github.com/mwouts/jupytext/tree/main/demo).
+

notebookx_py-0.1.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+notebookx/__init__.py,sha256=kK7_P9a02_SBXfaYDWEE5DYqhPgMA6A_YJrSdrtOTGk,957
+notebookx/__init__.pyi,sha256=WXRgS5OX-tr0UpdnJmdgcFrBmo317363GULeEcSAqVQ,8113
+notebookx/_notebookx.abi3.so,sha256=0WgbiXL_YRdOQAXDat3s-k0fJdsRA6Tq0Vo_T9cyz7Y,1923944
+notebookx/cli.py,sha256=k8gV4XZb_P7y0eUFNJ5RYT6lH43p8yo2Luo4Mj-rBCU,416
+notebookx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+notebookx_py-0.1.4.dist-info/METADATA,sha256=jjnN-xwxh90d9KGVf0uvoIhxOW0inSlWdKwqmxxtCO4,6115
+notebookx_py-0.1.4.dist-info/WHEEL,sha256=fqFHtOCr25M-h-Mnj-0-ZSwuoI9vJMsUUAJdvV4MPAM,145
+notebookx_py-0.1.4.dist-info/entry_points.txt,sha256=a8b4xNM2VIhf_DwwW3BzuxQKjdh7auuXAbJM0R7xdHk,45
+notebookx_py-0.1.4.dist-info/licenses/LICENSE,sha256=HMBDSL1PculP-vHW-UyR_8pG7x63usGRPXThVLs2b-k,1078
+notebookx_py-0.1.4.dist-info/RECORD,,

notebookx_py-0.1.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: maturin (1.10.2)
+Root-Is-Purelib: false
+Tag: cp38-abi3-manylinux_2_17_aarch64
+Tag: cp38-abi3-manylinux2014_aarch64

notebookx_py-0.1.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nbx=notebookx.cli:cli_main

notebookx_py-0.1.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lukas Takaaki Kikuchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.