Metadata-Version: 2.4
Name: supernote
Version: 0.11.1
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"
Requires-Dist: SQLAlchemy[asyncio]>=2.0.0; extra == "server"
Requires-Dist: alembic>=1.13.0; extra == "server"
Requires-Dist: aiosqlite>=0.19.0; extra == "server"
Requires-Dist: aiofiles>=25.1.0; extra == "server"
Requires-Dist: aiohttp-remotes>=1.3.0; 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 (Private) Cloud 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 Setup

To set up the project for development, please refer to the [Contributing Guide](docs/CONTRIBUTING.md).

## 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.


### Server Setup & Bootstrap

1. **Start the Server**:
   ```bash
   supernote serve
   ```

2. **Register the Admin**:
   The first user registered becomes the system administrator.
   ```bash
   supernote admin user add email@example.com --url http://localhost:8080
   ```

3. **Login to CLI**:
   ```bash
   supernote cloud-login email@example.com --url http://localhost:8080
   ```

See the [Bootstrap Guide](docs/bootstrap_guide.md) for detailed deployment and security instructions.

### Run with Docker

```bash
# Build image
docker build -t supernote .

# Run server
docker run -d -p 8080:8080 -v $(pwd)/storage:/storage supernote serve
```

See [Server Documentation](https://github.com/allenporter/supernote-lite/blob/main/supernote/server/README.mdd) 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 notebook convert input.note output.pdf
supernote notebook analyze input.note

# Server operations
supernote serve
supernote admin user list
supernote admin user add email@example.com

# Client operations
supernote cloud-login --url http://localhost:8080 email@example.com
supernote cloud-ls
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for details on:
- Local development setup
- Project architecture
- Coding standards
- Running tests

## 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.
