remarkable-tools 0.2.1__tar.gz

remarkable_tools-0.2.1/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2025 Gustaf Hendeby
+
+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.

remarkable_tools-0.2.1/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: remarkable-tools
+Version: 0.2.1
+Summary: A set of tools to interact with reMarkable tablets
+Keywords: remarkable,pdf
+Author: Gustaf Hendeby
+Author-email: Gustaf Hendeby <hendeby@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: pikepdf>=10.5.1
+Requires-Dist: requests>=2.32.5
+Requires-Dist: textual>=8.0.0
+Requires-Dist: textual-fspicker>=1.0.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# remarkable
+
+Utilities for interacting with a reMarkable tablet and post-processing exported PDFs.
+
+This project installs two command-line scripts:
+
+- `remarkable`: terminal UI and automation commands for browsing, downloading, and uploading documents.
+- `remarkable-hlfix`: PDF post-processing tool that reduces highlight opacity.
+
+## Installation
+
+Install the package in your current environment:
+
+```bash
+uv sync
+```
+
+Then run scripts with `uv run`:
+
+```bash
+uv run remarkable --help
+uv run remarkable-hlfix --help
+```
+
+If installed as a tool or package entry point, you can call `remarkable` and `remarkable-hlfix` directly.
+
+## Script: remarkable
+
+`remarkable` connects to the tablet over the reMarkable local interface (`http://10.11.99.1`) and supports both interactive and one-shot modes.
+
+### Configuration files
+
+Defaults are loaded from these files (later files override earlier ones):
+
+Linux/Unix:
+
+1. `/usr/local/etc/remarkableconfig`
+2. `$XDG_CONFIG_HOME/remarkable/config`
+3. `~/.config/remarkable/config`
+4. `~/.remarkableconfig`
+
+Windows:
+
+1. `%PROGRAMDATA%/remarkable/config`
+2. `%APPDATA%/remarkable/config`
+3. `%LOCALAPPDATA%/remarkable/config`
+4. `%USERPROFILE%/.remarkableconfig`
+
+Expected format:
+
+```toml
+[general]
+hl_fix = true
+tag = ""
+start_folder = ""
+```
+
+Command-line arguments override config values.
+
+### Usage
+
+Start the interactive browser:
+
+```bash
+remarkable
+```
+
+Start in a specific folder title path:
+
+```bash
+remarkable "Work/Meetings"
+```
+
+Download newest document and exit:
+
+```bash
+remarkable --get-newest
+```
+
+Download newest document matching a tag suffix:
+
+```bash
+remarkable --get-newest --tag _notes
+```
+
+Upload a file and exit:
+
+```bash
+remarkable --upload-file ./document.pdf
+```
+
+Disable highlight fixing for downloaded PDFs:
+
+```bash
+remarkable --no-hl-fix
+```
+
+Show installed/runtime version:
+
+```bash
+remarkable --version
+```
+
+### Interactive keys
+
+- `q`: quit
+- `F5`: refresh
+- `h`: toggle highlight fix for PDF downloads
+- In folder list: `Enter` to open folder
+- In document list: `d` to download PDF, `D` to download `.rmdoc`
+
+## Script: remarkable-hlfix
+
+`remarkable-hlfix` rewrites a PDF so reMarkable-style highlights are no longer fully opaque.
+
+Default behavior:
+
+- Targets known reMarkable highlight colors.
+- Reduces fully opaque highlight fill and stroke opacity from `1.0` to `0.4`.
+- Preserves graphics-state scoping (`q`/`Q`) so opacity changes do not leak between sibling drawing blocks.
+
+### Usage
+
+Basic conversion:
+
+```bash
+remarkable-hlfix input.pdf output.pdf
+```
+
+Run with default filenames (`input.pdf` -> `output.pdf`):
+
+```bash
+remarkable-hlfix
+```
+
+Apply to all fully opaque filled shapes instead of only known highlight colors:
+
+```bash
+remarkable-hlfix input.pdf output.pdf --all-colors
+```
+
+Tune minimum stroke width required before applying stroke transparency:
+
+```bash
+remarkable-hlfix input.pdf output.pdf --min-stroke-width 4.0
+```
+
+Detect highlight palette from one page and print a paste-ready color block:
+
+```bash
+remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1
+```
+
+Show installed/runtime version:
+
+```bash
+remarkable-hlfix --version
+```
+
+## Troubleshooting
+
+### remarkable cannot connect to device
+
+Symptoms:
+
+- Requests fail or time out.
+- You see connection errors when listing folders or downloading files.
+
+Checks:
+
+1. Ensure the tablet is connected over USB and USB web interface access is enabled.
+2. Verify the endpoint is reachable:
+
+```bash
+curl -I http://10.11.99.1/documents/
+```
+
+3. If needed, retry after reconnecting the cable and restarting the tablet's USB web interface.
+
+### config-related startup failure
+
+If you use a config file, ensure it contains a `[general]` table:
+
+```toml
+[general]
+hl_fix = true
+tag = ""
+start_folder = ""
+```
+
+If you are testing quickly, run with explicit flags to avoid relying on config values.
+
+### downloaded PDF highlights look unchanged
+
+Try one of these:
+
+1. Make sure highlight fixing is enabled (`--hl-fix` or toggle `h` in the UI).
+2. Run a direct pass with `remarkable-hlfix`.
+3. If your document uses non-standard colors, run calibration first:
+
+```bash
+remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1
+```
+
+4. If highlights are very thin, lower the stroke threshold:
+
+```bash
+remarkable-hlfix input.pdf output.pdf --min-stroke-width 1.0
+```
+
+### remarkable-hlfix input errors
+
+Common causes:
+
+- Input path is wrong.
+- File is encrypted or malformed.
+- Calibration page number does not exist in the PDF.
+
+Checks:
+
+1. Confirm file paths are correct.
+2. Start with the basic command:
+
+```bash
+remarkable-hlfix input.pdf output.pdf
+```
+
+3. If that fails, try opening and re-saving the PDF with another tool, then run again.

remarkable_tools-0.2.1/README.md

@@ -0,0 +1,228 @@
+# remarkable
+
+Utilities for interacting with a reMarkable tablet and post-processing exported PDFs.
+
+This project installs two command-line scripts:
+
+- `remarkable`: terminal UI and automation commands for browsing, downloading, and uploading documents.
+- `remarkable-hlfix`: PDF post-processing tool that reduces highlight opacity.
+
+## Installation
+
+Install the package in your current environment:
+
+```bash
+uv sync
+```
+
+Then run scripts with `uv run`:
+
+```bash
+uv run remarkable --help
+uv run remarkable-hlfix --help
+```
+
+If installed as a tool or package entry point, you can call `remarkable` and `remarkable-hlfix` directly.
+
+## Script: remarkable
+
+`remarkable` connects to the tablet over the reMarkable local interface (`http://10.11.99.1`) and supports both interactive and one-shot modes.
+
+### Configuration files
+
+Defaults are loaded from these files (later files override earlier ones):
+
+Linux/Unix:
+
+1. `/usr/local/etc/remarkableconfig`
+2. `$XDG_CONFIG_HOME/remarkable/config`
+3. `~/.config/remarkable/config`
+4. `~/.remarkableconfig`
+
+Windows:
+
+1. `%PROGRAMDATA%/remarkable/config`
+2. `%APPDATA%/remarkable/config`
+3. `%LOCALAPPDATA%/remarkable/config`
+4. `%USERPROFILE%/.remarkableconfig`
+
+Expected format:
+
+```toml
+[general]
+hl_fix = true
+tag = ""
+start_folder = ""
+```
+
+Command-line arguments override config values.
+
+### Usage
+
+Start the interactive browser:
+
+```bash
+remarkable
+```
+
+Start in a specific folder title path:
+
+```bash
+remarkable "Work/Meetings"
+```
+
+Download newest document and exit:
+
+```bash
+remarkable --get-newest
+```
+
+Download newest document matching a tag suffix:
+
+```bash
+remarkable --get-newest --tag _notes
+```
+
+Upload a file and exit:
+
+```bash
+remarkable --upload-file ./document.pdf
+```
+
+Disable highlight fixing for downloaded PDFs:
+
+```bash
+remarkable --no-hl-fix
+```
+
+Show installed/runtime version:
+
+```bash
+remarkable --version
+```
+
+### Interactive keys
+
+- `q`: quit
+- `F5`: refresh
+- `h`: toggle highlight fix for PDF downloads
+- In folder list: `Enter` to open folder
+- In document list: `d` to download PDF, `D` to download `.rmdoc`
+
+## Script: remarkable-hlfix
+
+`remarkable-hlfix` rewrites a PDF so reMarkable-style highlights are no longer fully opaque.
+
+Default behavior:
+
+- Targets known reMarkable highlight colors.
+- Reduces fully opaque highlight fill and stroke opacity from `1.0` to `0.4`.
+- Preserves graphics-state scoping (`q`/`Q`) so opacity changes do not leak between sibling drawing blocks.
+
+### Usage
+
+Basic conversion:
+
+```bash
+remarkable-hlfix input.pdf output.pdf
+```
+
+Run with default filenames (`input.pdf` -> `output.pdf`):
+
+```bash
+remarkable-hlfix
+```
+
+Apply to all fully opaque filled shapes instead of only known highlight colors:
+
+```bash
+remarkable-hlfix input.pdf output.pdf --all-colors
+```
+
+Tune minimum stroke width required before applying stroke transparency:
+
+```bash
+remarkable-hlfix input.pdf output.pdf --min-stroke-width 4.0
+```
+
+Detect highlight palette from one page and print a paste-ready color block:
+
+```bash
+remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1
+```
+
+Show installed/runtime version:
+
+```bash
+remarkable-hlfix --version
+```
+
+## Troubleshooting
+
+### remarkable cannot connect to device
+
+Symptoms:
+
+- Requests fail or time out.
+- You see connection errors when listing folders or downloading files.
+
+Checks:
+
+1. Ensure the tablet is connected over USB and USB web interface access is enabled.
+2. Verify the endpoint is reachable:
+
+```bash
+curl -I http://10.11.99.1/documents/
+```
+
+3. If needed, retry after reconnecting the cable and restarting the tablet's USB web interface.
+
+### config-related startup failure
+
+If you use a config file, ensure it contains a `[general]` table:
+
+```toml
+[general]
+hl_fix = true
+tag = ""
+start_folder = ""
+```
+
+If you are testing quickly, run with explicit flags to avoid relying on config values.
+
+### downloaded PDF highlights look unchanged
+
+Try one of these:
+
+1. Make sure highlight fixing is enabled (`--hl-fix` or toggle `h` in the UI).
+2. Run a direct pass with `remarkable-hlfix`.
+3. If your document uses non-standard colors, run calibration first:
+
+```bash
+remarkable-hlfix input.pdf --calibrate-palette --calibration-page 1
+```
+
+4. If highlights are very thin, lower the stroke threshold:
+
+```bash
+remarkable-hlfix input.pdf output.pdf --min-stroke-width 1.0
+```
+
+### remarkable-hlfix input errors
+
+Common causes:
+
+- Input path is wrong.
+- File is encrypted or malformed.
+- Calibration page number does not exist in the PDF.
+
+Checks:
+
+1. Confirm file paths are correct.
+2. Start with the basic command:
+
+```bash
+remarkable-hlfix input.pdf output.pdf
+```
+
+3. If that fails, try opening and re-saving the PDF with another tool, then run again.

remarkable_tools-0.2.1/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "remarkable-tools"
+version = "0.2.1"
+description = "A set of tools to interact with reMarkable tablets"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+authors = [
+    { name = "Gustaf Hendeby", email = "hendeby@gmail.com" }
+]
+keywords = ["remarkable", "pdf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "pikepdf>=10.5.1",
+    "requests>=2.32.5",
+    "textual>=8.0.0",
+    "textual-fspicker>=1.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "pytest-cov>=6.0",
+    "ruff>=0.14.11",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "remarkable"
+
+[project.scripts]
+remarkable = "remarkable.ui:main"
+remarkable-hlfix = "remarkable.hl_fix:main"
+
+[tool.uv.sources]
+remarkable-tools = { index = "testpypi" }
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

remarkable_tools-0.2.1/src/remarkable/helpers.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import importlib.metadata as importlib_metadata
+import logging
+import os
+import tomllib
+import typing
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+
+def deep_merge(
+  parent_source: dict[str, typing.Any], source: dict[str, typing.Any]
+) -> dict[str, typing.Any]:
+  result = parent_source.copy()
+  for k, v in source.items():
+    if k in result and isinstance(result[k], dict) and isinstance(v, dict):
+      result[k] = deep_merge(result[k], v)
+    else:
+      result[k] = v
+  return result
+
+
+def get_config_paths(platform: str | None = None) -> list[Path]:
+  home = Path.home()
+  if (platform or os.name) == "nt":
+    config_paths: list[Path] = []
+    for env_var in ("PROGRAMDATA", "APPDATA", "LOCALAPPDATA"):
+      config_dir = os.getenv(env_var)
+      if config_dir:
+        config_paths.append(Path(config_dir) / "remarkable" / "config")
+    config_paths.append(home / ".remarkableconfig")
+    return config_paths
+
+  config_paths = [Path("/") / "usr" / "local" / "etc" / "remarkableconfig"]
+  xdg_config_home = os.getenv("XDG_CONFIG_HOME")
+  if xdg_config_home:
+    config_paths.append(Path(xdg_config_home) / "remarkable" / "config")
+  config_paths.append(home / ".config" / "remarkable" / "config")
+  config_paths.append(home / ".remarkableconfig")
+  return config_paths
+
+
+def parse_config(default: dict[str, typing.Any]) -> dict[str, typing.Any]:
+  config_paths = get_config_paths()
+  config = default
+  for path in config_paths:
+    if not path.is_file():
+      continue
+    log.info("Loading configs from: %s", path)
+    with path.open("rb") as f:
+      data = tomllib.load(f)
+    log.info("Loaded config from %s: %s", path, data)
+    config = deep_merge(config, data)
+  return config
+
+
+def get_runtime_version(dist_name: str = "remarkable") -> str:
+  """Return installed package version, or fall back to pyproject.toml."""
+  try:
+    return importlib_metadata.version(dist_name)
+  except importlib_metadata.PackageNotFoundError:
+    pass
+
+  pyproject_path = Path(__file__).resolve().parents[2] / "pyproject.toml"
+  try:
+    with pyproject_path.open("rb") as f:
+      pyproject_data = tomllib.load(f)
+    return str(pyproject_data["project"]["version"])
+  except OSError, tomllib.TOMLDecodeError, KeyError, TypeError:
+    return "unknown"