supernote 0.3.0__tar.gz → 0.4.0__tar.gz

supernote-0.4.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: supernote
+Version: 0.4.0
+Summary: All-in-one toolkit for Supernote devices: parse notebooks, self-host services, access services
+Author-email: jya <jya@wizmy.net>, Allen Porter <allen.porter@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Source, https://github.com/allenporter/supernote
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colour>=0.1.5
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: Pillow>=7.2.0
+Requires-Dist: potracer>=0.0.1
+Requires-Dist: pypng>=0.0.20
+Requires-Dist: reportlab>=3.6.1
+Requires-Dist: svgwrite>=1.4
+Provides-Extra: client
+Requires-Dist: aiohttp; extra == "client"
+Requires-Dist: requests; extra == "client"
+Requires-Dist: tqdm; extra == "client"
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.13.2; extra == "server"
+Requires-Dist: mashumaro>=3.17; extra == "server"
+Requires-Dist: pyyaml>=6.0; extra == "server"
+Requires-Dist: PyJWT>=2.10.1; extra == "server"
+Provides-Extra: all
+Requires-Dist: supernote[client,server]; extra == "all"
+Dynamic: license-file
+
+# supernote
+
+All-in-one toolkit for Supernote devices: parse notebooks, self host, and access services.
+
+This content is shared between the [documentation](https://allenporter.github.io/supernote-lite/) and github repository at [github.com/allenporter/supernote-lite](https://github.com/allenporter/supernote-lite).
+
+## Features
+
+- **Notebook Parsing**: Convert `.note` files to PDF, PNG, SVG, or text
+- **Private Server**: Self-hosted Supernote Private Cloud implementation
+- **Client**: Interact with Supernote service API
+
+## Installation
+
+```bash
+
+# Install specific components
+pip install supernote              # Notebook parsing only
+pip install supernote[server]      # + Private server
+pip install supernote[client]      # + Client
+
+# Full installation (recommended for server users)
+pip install supernote[all]
+```
+
+## Local Development
+
+Install in a virtual environment:
+
+```bash
+uv venv --python=3.14
+source .venv/bin/activate
+uv pip install -r requirements_dev.txt
+uv pip install -e ".[all]"
+```
+
+## Quick Start
+
+### Parse a Notebook
+
+```python
+from supernote.notebook import parse_notebook
+
+notebook = parse_notebook("mynote.note")
+notebook.to_pdf("output.pdf")
+```
+
+The notebook parser is a fork and slightly lighter dependency version of [supernote-tool](https://github.com/jya-dev/supernote-tool) that drops svg dependencies not found in some containers. Generally, you should probably prefer to use that original library unless there is a specific reason you're also having a similar dependency
+limitation. All credit goes to the original authors of [supernote-tool](https://github.com/jya-dev/supernote-tool) for providing an amazing low level utility.
+
+
+### Run Private Server
+
+```bash
+# Configure users (you will be prompted for a password)
+supernote-server user add alice
+
+# Start server
+supernote-server serve
+```
+
+### Run with Docker
+
+```bash
+# Build image
+docker build -t supernote-server .
+
+# Create user
+mkdir config
+docker run --rm -it -v $(pwd)/config:/config supernote-server supernote-server user add alice
+
+# Run server
+docker run -d -p 8080:8080 \
+  -v $(pwd)/config:/config \
+  -v $(pwd)/storage:/data \
+  supernote-server
+```
+
+See [Server Documentation](supernote/server/README.md) for details.
+
+
+### Access Supernote Services
+
+```python
+
+from supernote.client import SupernoteClient
+
+async with SupernoteClient.from_credentials(email, password) as client:
+    files = await client.list_files()
+```
+
+
+## CLI Usage
+
+```bash
+# Notebook operations
+supernote convert input.note output.pdf
+supernote analyze input.note
+
+# Server operations
+supernote-server serve
+supernote-server user add alice
+
+
+# Client operations
+supernote client login
+supernote client ls
+```
+
+## Development
+
+This package is designed for:
+1. **Server operators** - Self-hosting Supernote Private Cloud
+2. **Developers** - Integrating Supernote into applications
+3. **Reference** - Understanding Supernote protocols
+
+See [ARCHITECTURE.md](supernote/server/ARCHITECTURE.md) for protocol details.
+
+### Setup
+
+```bash
+uv venv --python=3.14
+source .venv/bin/activate
+uv pip install -r requirements_dev.txt
+uv pip install -e ".[all]"
+```
+
+## Credits
+
+The `supernote` library is a fork and slightly lighter dependency version of [supernote-tool](https://github.com/jya-dev/supernote-tool) that drops svg dependencies not found in some containers. Generally, you should probably prefer to use that library unless there is a specific reason you're also having a similar dependency limitation.
+
+## Acknowledgments
+
+This project is in support of the amazing [Ratta Supernote](https://supernote.com/) product and community. This project aims to be a complementary, unofficial offering that is compatible with the [Private Cloud feature](https://support.supernote.com/Whats-New/setting-up-your-own-supernote-private-cloud-beta), helping to support their open ecosystem, helping to reduce load on their servers etc (e.g. for AI
+powered personal assistant integrations that need to process notebooks, etc)
+
+### Comparison with Official Private Cloud
+
+Ratta offers an [official Private Cloud solution](https://support.supernote.com/Whats-New/setting-up-your-own-supernote-private-cloud-beta) based on Docker. You
+should generally prefer that solution, unless you are interested in lower level
+integrations and are comfortable managing your own security, SSL, etc.
+
+Here is how this project compares:
+
+| Feature | Official Private Cloud | Supernote-Lite (This Project) |
+|---------|------------------------|-------------------------------|
+| **Type** | Official Product | Community Project |
+| **Technology** | Docker Container (Java/Spring) | Python Package |
+| **Source** | Closed Source | Open Source |
+| **Focus** | Stability & End-Users | Hackability & Developers |
+| **Requirements** | Docker Environment | Python 3.10+ |
+| **Extensibility** | Low (Black Box) | High (Modular Codebase) |
+| **Security/SSL** | Documented Guides Included | DIY (Bring Your Own Proxy) |
+
+**Use the Official Private Cloud if:**
+- You want a supported, "set-and-forget" solution.
+- You prefer using Docker containers.
+
+**Use Supernote-Lite if:**
+- You want to understand how the protocol works.
+- You want to run on low-power hardware without Docker overhead.
+- You want to integrate Supernote sync into your own Python applications.
+- You want to customize the server behavior.
+
+### Community Projects
+
+- [github.com/jya-dev/supernote-tool](https://github.com/jya-dev/supernote-tool) - Unofficial python tool for Ratta Supernote for parsing notebook files, which this projects notebook module is based on.
+- [github.com/philips/supernote-typescript](https://github.com/philips/supernote-typescript) - Supernote file-format support in typescript
+- [github.com/julianprester/sncloud](https://github.com/julianprester/sncloud) - Supernote Cloud API for Python
+- [github.com/fharper/awesome-supernote](https://github.com/fharper/awesome-supernote) - A curated list of Supernote resources
+- [github.com/philips/supernote-obsidian-plugin](https://github.com/philips/supernote-obsidian-plugin) - Obsidian plugin for Supernote
+- [github.com/jbchouinard/supernote-sync](https://github.com/jbchouinard/supernote-sync) - Tool to automatically backup files from the Supernote using local WiFi using the Supernote Browse & Access feature
+- [github.com/theburningbush/snbackup](https://github.com/theburningbush/snbackup) - CLI tool for wireless Supernote backups using the Browse & Access feature
+- [github.com/dsummersl/sn2md](https://github.com/dsummersl/sn2md) - Supernote to text/image converter (sn2md)
+- [github.com/calebc42/eink-template-gen](https://github.com/calebc42/eink-template-gen) - Generates pixel-perfect page templates for e-ink devices.

supernote-0.4.0/README.md

@@ -0,0 +1,175 @@
+# supernote
+
+All-in-one toolkit for Supernote devices: parse notebooks, self host, and access services.
+
+This content is shared between the [documentation](https://allenporter.github.io/supernote-lite/) and github repository at [github.com/allenporter/supernote-lite](https://github.com/allenporter/supernote-lite).
+
+## Features
+
+- **Notebook Parsing**: Convert `.note` files to PDF, PNG, SVG, or text
+- **Private Server**: Self-hosted Supernote Private Cloud implementation
+- **Client**: Interact with Supernote service API
+
+## Installation
+
+```bash
+
+# Install specific components
+pip install supernote              # Notebook parsing only
+pip install supernote[server]      # + Private server
+pip install supernote[client]      # + Client
+
+# Full installation (recommended for server users)
+pip install supernote[all]
+```
+
+## Local Development
+
+Install in a virtual environment:
+
+```bash
+uv venv --python=3.14
+source .venv/bin/activate
+uv pip install -r requirements_dev.txt
+uv pip install -e ".[all]"
+```
+
+## Quick Start
+
+### Parse a Notebook
+
+```python
+from supernote.notebook import parse_notebook
+
+notebook = parse_notebook("mynote.note")
+notebook.to_pdf("output.pdf")
+```
+
+The notebook parser is a fork and slightly lighter dependency version of [supernote-tool](https://github.com/jya-dev/supernote-tool) that drops svg dependencies not found in some containers. Generally, you should probably prefer to use that original library unless there is a specific reason you're also having a similar dependency
+limitation. All credit goes to the original authors of [supernote-tool](https://github.com/jya-dev/supernote-tool) for providing an amazing low level utility.
+
+
+### Run Private Server
+
+```bash
+# Configure users (you will be prompted for a password)
+supernote-server user add alice
+
+# Start server
+supernote-server serve
+```
+
+### Run with Docker
+
+```bash
+# Build image
+docker build -t supernote-server .
+
+# Create user
+mkdir config
+docker run --rm -it -v $(pwd)/config:/config supernote-server supernote-server user add alice
+
+# Run server
+docker run -d -p 8080:8080 \
+  -v $(pwd)/config:/config \
+  -v $(pwd)/storage:/data \
+  supernote-server
+```
+
+See [Server Documentation](supernote/server/README.md) for details.
+
+
+### Access Supernote Services
+
+```python
+
+from supernote.client import SupernoteClient
+
+async with SupernoteClient.from_credentials(email, password) as client:
+    files = await client.list_files()
+```
+
+
+## CLI Usage
+
+```bash
+# Notebook operations
+supernote convert input.note output.pdf
+supernote analyze input.note
+
+# Server operations
+supernote-server serve
+supernote-server user add alice
+
+
+# Client operations
+supernote client login
+supernote client ls
+```
+
+## Development
+
+This package is designed for:
+1. **Server operators** - Self-hosting Supernote Private Cloud
+2. **Developers** - Integrating Supernote into applications
+3. **Reference** - Understanding Supernote protocols
+
+See [ARCHITECTURE.md](supernote/server/ARCHITECTURE.md) for protocol details.
+
+### Setup
+
+```bash
+uv venv --python=3.14
+source .venv/bin/activate
+uv pip install -r requirements_dev.txt
+uv pip install -e ".[all]"
+```
+
+## Credits
+
+The `supernote` library is a fork and slightly lighter dependency version of [supernote-tool](https://github.com/jya-dev/supernote-tool) that drops svg dependencies not found in some containers. Generally, you should probably prefer to use that library unless there is a specific reason you're also having a similar dependency limitation.
+
+## Acknowledgments
+
+This project is in support of the amazing [Ratta Supernote](https://supernote.com/) product and community. This project aims to be a complementary, unofficial offering that is compatible with the [Private Cloud feature](https://support.supernote.com/Whats-New/setting-up-your-own-supernote-private-cloud-beta), helping to support their open ecosystem, helping to reduce load on their servers etc (e.g. for AI
+powered personal assistant integrations that need to process notebooks, etc)
+
+### Comparison with Official Private Cloud
+
+Ratta offers an [official Private Cloud solution](https://support.supernote.com/Whats-New/setting-up-your-own-supernote-private-cloud-beta) based on Docker. You
+should generally prefer that solution, unless you are interested in lower level
+integrations and are comfortable managing your own security, SSL, etc.
+
+Here is how this project compares:
+
+| Feature | Official Private Cloud | Supernote-Lite (This Project) |
+|---------|------------------------|-------------------------------|
+| **Type** | Official Product | Community Project |
+| **Technology** | Docker Container (Java/Spring) | Python Package |
+| **Source** | Closed Source | Open Source |
+| **Focus** | Stability & End-Users | Hackability & Developers |
+| **Requirements** | Docker Environment | Python 3.10+ |
+| **Extensibility** | Low (Black Box) | High (Modular Codebase) |
+| **Security/SSL** | Documented Guides Included | DIY (Bring Your Own Proxy) |
+
+**Use the Official Private Cloud if:**
+- You want a supported, "set-and-forget" solution.
+- You prefer using Docker containers.
+
+**Use Supernote-Lite if:**
+- You want to understand how the protocol works.
+- You want to run on low-power hardware without Docker overhead.
+- You want to integrate Supernote sync into your own Python applications.
+- You want to customize the server behavior.
+
+### Community Projects
+
+- [github.com/jya-dev/supernote-tool](https://github.com/jya-dev/supernote-tool) - Unofficial python tool for Ratta Supernote for parsing notebook files, which this projects notebook module is based on.
+- [github.com/philips/supernote-typescript](https://github.com/philips/supernote-typescript) - Supernote file-format support in typescript
+- [github.com/julianprester/sncloud](https://github.com/julianprester/sncloud) - Supernote Cloud API for Python
+- [github.com/fharper/awesome-supernote](https://github.com/fharper/awesome-supernote) - A curated list of Supernote resources
+- [github.com/philips/supernote-obsidian-plugin](https://github.com/philips/supernote-obsidian-plugin) - Obsidian plugin for Supernote
+- [github.com/jbchouinard/supernote-sync](https://github.com/jbchouinard/supernote-sync) - Tool to automatically backup files from the Supernote using local WiFi using the Supernote Browse & Access feature
+- [github.com/theburningbush/snbackup](https://github.com/theburningbush/snbackup) - CLI tool for wireless Supernote backups using the Browse & Access feature
+- [github.com/dsummersl/sn2md](https://github.com/dsummersl/sn2md) - Supernote to text/image converter (sn2md)
+- [github.com/calebc42/eink-template-gen](https://github.com/calebc42/eink-template-gen) - Generates pixel-perfect page templates for e-ink devices.

{supernote-0.3.0 → supernote-0.4.0}/pyproject.toml

@@ -4,10 +4,10 @@ requires = ["setuptools>=77.0"]
 
 [project]
 name = "supernote"
-version = "0.3.0"
+version = "0.4.0"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
-description = "Unofficial python library for parsing Supernote notebooks"
+description = "All-in-one toolkit for Supernote devices: parse notebooks, self-host services, access services"
 readme = "README.md"
 authors = [
   { name = "jya", email = "jya@wizmy.net" },
@@ -16,7 +16,7 @@ authors = [
 requires-python = ">=3.13"
 classifiers = []
 dependencies = [
-  # Notebook dependencies
+  # Core notebook dependencies (always installed)
   "colour>=0.1.5",
   "numpy>=1.19.0",
   "Pillow>=7.2.0",
@@ -24,11 +24,21 @@ dependencies = [
   "pypng>=0.0.20",
   "reportlab>=3.6.1",
   "svgwrite>=1.4",
+]
 
-  # Cloud dependencies
+[project.optional-dependencies]
+client = [
+    "aiohttp",
+    "requests",
+    "tqdm",
+]
+server = [
   "aiohttp>=3.13.2",
   "mashumaro>=3.17",
+  "pyyaml>=6.0",
+  "PyJWT>=2.10.1",
 ]
+all = ["supernote[client,server]"]
 
 [project.urls]
 Source = "https://github.com/allenporter/supernote"
@@ -37,16 +47,20 @@ Source = "https://github.com/allenporter/supernote"
 include = ["supernote*"]
 
 [project.entry-points."console_scripts"]
-supernote-tool  = "supernote.cmds.supernote_tool:main"
+supernote = "supernote.cli.main:main"
+supernote-server = "supernote.cli.server:main"
 
 [tool.mypy]
 exclude = [
   "venv/",
-  "supernote/cmds/",
+  "data",
+  # TODO: Fix mypy errors and then remove this
+  "supernote/notebook/",
+  "supernote/cli/",
 ]
 platform = "linux"
 show_error_codes = true
-follow_imports = "normal"
+follow_imports = "silent"
 local_partial_types = true
 strict_equality = true
 no_implicit_optional = true

supernote-0.4.0/supernote/__init__.py

@@ -0,0 +1,26 @@
+"""
+.. include:: ../README.md
+"""
+
+# Core notebook parsing (always available)
+from . import notebook
+
+__all__ = [
+    "notebook",
+]
+
+# Optional: Client library
+try:
+    from . import client  # noqa: F401
+
+    __all__.extend(["client"])
+except ImportError:
+    pass
+
+# Optional: Server
+try:
+    from . import server  # noqa: F401
+
+    __all__.extend(["server"])
+except ImportError:
+    pass

supernote-0.3.0/supernote/cmds/cloud_login_tool.py → supernote-0.4.0/supernote/cli/client.py

@@ -1,19 +1,17 @@
-#!/usr/bin/env python3
-"""Cloud login debugging tool for Supernote Cloud."""
+"""Client CLI commands."""
 
 import asyncio
 import logging
-import sys
 import os
+import sys
 
 import aiohttp
 
-from supernote.cloud.client import Client
-from supernote.cloud.login_client import LoginClient
-from supernote.cloud.auth import FileCacheAuth
-from supernote.cloud.cloud_client import SupernoteCloudClient
-from supernote.cloud.exceptions import SupernoteException
-
+from supernote.client.auth import FileCacheAuth
+from supernote.client.client import Client
+from supernote.client.cloud_client import SupernoteClient
+from supernote.client.exceptions import SupernoteException
+from supernote.client.login_client import LoginClient
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -72,11 +70,7 @@ async def async_cloud_login(email: str, password: str, verbose: bool = False) ->
                 access_token = await login_client.login(email, password)
             except SupernoteException as err:
                 # Check if it's an SMS verification requirement
-                # We do this by checking the exception type, but since we just added it
-                # we need to make sure we import it.
-                # For now, let's assume if the message contains "verification code" it is one.
-                # But better to use the type.
-                from supernote.cloud.exceptions import SmsVerificationRequired
+                from supernote.client.exceptions import SmsVerificationRequired
 
                 if isinstance(err, SmsVerificationRequired):
                     print()
@@ -120,9 +114,8 @@ async def async_cloud_login(email: str, password: str, verbose: bool = False) ->
 
             # Step 2: Test basic functionality
             print("Step 3: Testing basic functionality...")
-            # auth = ConstantAuth(access_token) # No longer needed as we use FileCacheAuth
             authenticated_client = Client(session, auth=auth)
-            cloud_client = SupernoteCloudClient(authenticated_client)
+            cloud_client = SupernoteClient(authenticated_client)
 
             # Test 1: Query user
             print("  Test 1: Querying user information...")
@@ -185,33 +178,25 @@ async def async_cloud_login(email: str, password: str, verbose: bool = False) ->
 
 
 def subcommand_cloud_login(args) -> None:
-    """Handler for cloud-login subcommand.
-
-    Args:
-        args: Parsed command line arguments
-    """
+    """Handler for cloud-login subcommand."""
     asyncio.run(async_cloud_login(args.email, args.password, args.verbose))
 
 
 async def async_cloud_ls(verbose: bool = False) -> None:
-    """List files in Supernote Cloud using cached credentials.
-
-    Args:
-        verbose: Enable verbose logging
-    """
+    """List files in Supernote Cloud using cached credentials."""
     setup_logging(verbose)
 
     cache_path = os.path.expanduser("~/.cache/supernote.pkl")
     if not os.path.exists(cache_path):
         print(f"Error: No cached credentials found at {cache_path}")
-        print("Please run 'supernote-tool cloud-login' first.")
+        print("Please run 'supernote cloud login' first.")
         sys.exit(1)
 
     async with aiohttp.ClientSession() as session:
         try:
             auth = FileCacheAuth(cache_path)
             client = Client(session, auth=auth)
-            cloud_client = SupernoteCloudClient(client)
+            cloud_client = SupernoteClient(client)
 
             print("Listing files in root directory...")
             file_list_response = await cloud_client.file_list()
@@ -239,9 +224,27 @@ async def async_cloud_ls(verbose: bool = False) -> None:
 
 
 def subcommand_cloud_ls(args) -> None:
-    """Handler for cloud-ls subcommand.
-
-    Args:
-        args: Parsed command line arguments
-    """
+    """Handler for cloud-ls subcommand."""
     asyncio.run(async_cloud_ls(args.verbose))
+
+
+def add_parser(subparsers):
+    # 'cloud-login' subcommand
+    parser_cloud_login = subparsers.add_parser(
+        "cloud-login", help="debug Supernote Cloud login flow"
+    )
+    parser_cloud_login.add_argument("email", type=str, help="user email/account")
+    parser_cloud_login.add_argument("password", type=str, help="user password")
+    parser_cloud_login.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose logging"
+    )
+    parser_cloud_login.set_defaults(func=subcommand_cloud_login)
+
+    # Cloud ls command
+    cloud_ls_parser = subparsers.add_parser(
+        "cloud-ls", help="List files in Supernote Cloud"
+    )
+    cloud_ls_parser.add_argument(
+        "-v", "--verbose", action="store_true", help="Enable verbose logging"
+    )
+    cloud_ls_parser.set_defaults(func=subcommand_cloud_ls)

supernote-0.4.0/supernote/cli/main.py

@@ -0,0 +1,41 @@
+"""Main CLI entry point."""
+
+import argparse
+import sys
+
+from . import client, notebook, server
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="supernote",
+        description="Supernote toolkit for parsing, self hosting, and service access",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # Notebook commands
+    notebook.add_parser(subparsers)
+
+    # Client commands
+    client.add_parser(subparsers)
+
+    # Server commands
+    server.add_parser(subparsers)
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    # Dispatch to appropriate handler
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()