s2k-cli 0.1.0__tar.gz

s2k_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marco Fura
+
+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.

s2k_cli-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.3
+Name: s2k-cli
+Version: 0.1.0
+Summary: Send local files to your Kindle from the command line.
+License: MIT
+Keywords: kindle,send-to-kindle,ebook,email,cli
+Author: Marco Fura
+Author-email: mjfura27@gmail.com
+Requires-Python: >=3.13,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Dist: email-validator (>=2.3,<3.0)
+Requires-Dist: pydantic (>=2.13,<3.0)
+Requires-Dist: pydantic-settings (>=2.15,<3.0)
+Requires-Dist: python-dotenv (>=1.2,<2.0)
+Requires-Dist: typer (>=0.27,<1.0)
+Project-URL: Homepage, https://github.com/mjfura/send-2-kindle
+Project-URL: Issues, https://github.com/mjfura/send-2-kindle/issues
+Project-URL: Repository, https://github.com/mjfura/send-2-kindle
+Description-Content-Type: text/markdown
+
+# s2k — send files to your Kindle
+
+`s2k` emails documents to your Kindle through Amazon's Send to Kindle service, one email per file.
+
+```bash
+s2k send book.epub paper.pdf notes.docx
+```
+
+Supported: `.pdf .epub .doc .docx .txt .rtf .html .htm .jpg .jpeg .png .gif .bmp`, up to 50 MB
+each (your email provider may allow less: Gmail rejects files above roughly 18 MB).
+
+## Install
+
+Requires Python 3.13+.
+
+```bash
+pipx install s2k-cli       # or: uv tool install s2k-cli
+```
+
+## Set up
+
+1. **In Amazon** (*Manage Your Content and Devices → Preferences → Personal Document Settings*):
+   copy your `@kindle.com` address and add the email you will send from to the *Approved Personal
+   Document E-mail List*.
+2. **Gmail users:** create an app password at <https://myaccount.google.com/apppasswords>
+   (requires 2-Step Verification). Your normal Gmail password will not work.
+3. Run the wizard in your terminal — it asks for the values, hides the password, saves them to
+   `~/.config/s2k/config.env` with private permissions and offers to test the login:
+   ```bash
+   s2k init
+   ```
+4. Check that everything is ready at any time (sends nothing):
+   ```bash
+   s2k doctor
+   ```
+
+## Usage
+
+```bash
+s2k send FILE...    # send files, one email each
+s2k doctor          # check configuration and SMTP login
+s2k init            # create or update the configuration
+s2k --version
+```
+
+Exit codes: `0` success · `1` something failed (see the report) · `2` invalid configuration or usage.
+
+"Sent" means your email provider accepted the message. If Amazon rejects it (for example, the
+sender is not approved), Amazon emails you.
+
+## Configuration
+
+Read from, highest priority first: environment variables → the file in `S2K_CONFIG_FILE` →
+`$XDG_CONFIG_HOME/s2k/config.env` → `~/.config/s2k/config.env`.
+
+| Variable | Required | Default |
+|---|---|---|
+| `S2K_KINDLE_EMAIL` | yes | — |
+| `S2K_SENDER_EMAIL` | yes | — |
+| `S2K_SMTP_PASSWORD` | yes | — |
+| `S2K_SMTP_HOST` | no | `smtp.gmail.com` |
+| `S2K_SMTP_PORT` | no | `587` |
+| `S2K_SMTP_SECURITY` | no | `starttls` (`ssl` for port 465) |
+| `S2K_SMTP_USERNAME` | no | the sender address |
+
+## Troubleshooting
+
+| `s2k doctor` says | Do this |
+|---|---|
+| No configuration found | Run `s2k init` |
+| authentication failed … app password | Create a Gmail app password and run `s2k init` again |
+| could not connect | Check `S2K_SMTP_HOST`, `S2K_SMTP_PORT` and `S2K_SMTP_SECURITY` |
+| Config file is readable by other users | `chmod 600 ~/.config/s2k/config.env` |
+
+## License
+
+MIT
+

s2k_cli-0.1.0/README.md

@@ -0,0 +1,77 @@
+# s2k — send files to your Kindle
+
+`s2k` emails documents to your Kindle through Amazon's Send to Kindle service, one email per file.
+
+```bash
+s2k send book.epub paper.pdf notes.docx
+```
+
+Supported: `.pdf .epub .doc .docx .txt .rtf .html .htm .jpg .jpeg .png .gif .bmp`, up to 50 MB
+each (your email provider may allow less: Gmail rejects files above roughly 18 MB).
+
+## Install
+
+Requires Python 3.13+.
+
+```bash
+pipx install s2k-cli       # or: uv tool install s2k-cli
+```
+
+## Set up
+
+1. **In Amazon** (*Manage Your Content and Devices → Preferences → Personal Document Settings*):
+   copy your `@kindle.com` address and add the email you will send from to the *Approved Personal
+   Document E-mail List*.
+2. **Gmail users:** create an app password at <https://myaccount.google.com/apppasswords>
+   (requires 2-Step Verification). Your normal Gmail password will not work.
+3. Run the wizard in your terminal — it asks for the values, hides the password, saves them to
+   `~/.config/s2k/config.env` with private permissions and offers to test the login:
+   ```bash
+   s2k init
+   ```
+4. Check that everything is ready at any time (sends nothing):
+   ```bash
+   s2k doctor
+   ```
+
+## Usage
+
+```bash
+s2k send FILE...    # send files, one email each
+s2k doctor          # check configuration and SMTP login
+s2k init            # create or update the configuration
+s2k --version
+```
+
+Exit codes: `0` success · `1` something failed (see the report) · `2` invalid configuration or usage.
+
+"Sent" means your email provider accepted the message. If Amazon rejects it (for example, the
+sender is not approved), Amazon emails you.
+
+## Configuration
+
+Read from, highest priority first: environment variables → the file in `S2K_CONFIG_FILE` →
+`$XDG_CONFIG_HOME/s2k/config.env` → `~/.config/s2k/config.env`.
+
+| Variable | Required | Default |
+|---|---|---|
+| `S2K_KINDLE_EMAIL` | yes | — |
+| `S2K_SENDER_EMAIL` | yes | — |
+| `S2K_SMTP_PASSWORD` | yes | — |
+| `S2K_SMTP_HOST` | no | `smtp.gmail.com` |
+| `S2K_SMTP_PORT` | no | `587` |
+| `S2K_SMTP_SECURITY` | no | `starttls` (`ssl` for port 465) |
+| `S2K_SMTP_USERNAME` | no | the sender address |
+
+## Troubleshooting
+
+| `s2k doctor` says | Do this |
+|---|---|
+| No configuration found | Run `s2k init` |
+| authentication failed … app password | Create a Gmail app password and run `s2k init` again |
+| could not connect | Check `S2K_SMTP_HOST`, `S2K_SMTP_PORT` and `S2K_SMTP_SECURITY` |
+| Config file is readable by other users | `chmod 600 ~/.config/s2k/config.env` |
+
+## License
+
+MIT

s2k_cli-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "s2k-cli"
+version = "0.1.0"
+description = "Send local files to your Kindle from the command line."
+authors = [{ name = "Marco Fura", email = "mjfura27@gmail.com" }]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["kindle", "send-to-kindle", "ebook", "email", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+]
+requires-python = ">=3.13,<4.0"
+dependencies = [
+    "typer (>=0.27,<1.0)",
+    "pydantic (>=2.13,<3.0)",
+    "pydantic-settings (>=2.15,<3.0)",
+    "email-validator (>=2.3,<3.0)",
+    "python-dotenv (>=1.2,<2.0)",
+]
+
+[project.scripts]
+s2k = "send_2_kindle.main:app"
+
+[project.urls]
+Homepage = "https://github.com/mjfura/send-2-kindle"
+Repository = "https://github.com/mjfura/send-2-kindle"
+Issues = "https://github.com/mjfura/send-2-kindle/issues"
+
+[tool.poetry]
+packages = [{ include = "send_2_kindle", from = "src" }]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^9.1"
+ruff = "^0.16"
+mypy = "^2.4"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF", "S", "PT"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+mypy_path = "src"
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"

s2k_cli-0.1.0/src/send_2_kindle/__init__.py

@@ -0,0 +1,10 @@
+"""s2k: send local files to your Kindle through the Send to Kindle email service."""
+
+from importlib.metadata import version
+
+DISTRIBUTION_NAME = "s2k-cli"
+
+
+def installed_version() -> str:
+    """Version of the installed s2k-cli distribution (single source: pyproject.toml)."""
+    return version(DISTRIBUTION_NAME)

s2k_cli-0.1.0/src/send_2_kindle/__main__.py

@@ -0,0 +1,3 @@
+from send_2_kindle.main import app
+
+app(prog_name="s2k")

s2k_cli-0.1.0/src/send_2_kindle/config.py

@@ -0,0 +1,116 @@
+"""Configuration loaded from S2K_* environment variables and the user's config file."""
+
+import os
+from pathlib import Path
+from typing import Annotated, Any, Final, Literal
+
+from dotenv import dotenv_values
+from pydantic import EmailStr, Field, SecretStr, ValidationError, field_validator
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+
+from send_2_kindle import constants
+from send_2_kindle.errors import ConfigError
+
+ENV_PREFIX: Final[str] = "S2K_"
+CONFIG_FILE_VARIABLE: Final[str] = "S2K_CONFIG_FILE"
+REQUIRED_VARIABLES: Final[tuple[str, ...]] = (
+    "S2K_KINDLE_EMAIL",
+    "S2K_SENDER_EMAIL",
+    "S2K_SMTP_PASSWORD",
+)
+
+# Field types shared by Settings and the `s2k init` wizard, so both validate the same way.
+SmtpHost = Annotated[str, Field(min_length=1)]
+SmtpPort = Annotated[int, Field(ge=1, le=65535)]
+SmtpSecurity = Literal["starttls", "ssl"]
+
+
+def config_file_path() -> Path:
+    """Return the config file s2k reads (it may not exist).
+
+    $S2K_CONFIG_FILE, else $XDG_CONFIG_HOME/s2k/config.env, else ~/.config/s2k/config.env.
+    """
+    override = os.environ.get(CONFIG_FILE_VARIABLE)
+    if override:
+        return Path(override).expanduser()
+    base = os.environ.get("XDG_CONFIG_HOME") or "~/.config"
+    return Path(base).expanduser() / "s2k" / "config.env"
+
+
+class Settings(BaseSettings):
+    """Validated s2k configuration. Real environment variables override the config file."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX, env_file_encoding="utf-8", extra="ignore"
+    )
+
+    kindle_email: EmailStr
+    sender_email: EmailStr
+    smtp_password: SecretStr
+    smtp_host: SmtpHost = constants.GMAIL_SMTP_HOST
+    smtp_port: SmtpPort = 587
+    smtp_security: SmtpSecurity = "starttls"
+    smtp_username: str | None = None
+
+    @field_validator("smtp_password")
+    @classmethod
+    def _password_not_empty(cls, value: SecretStr) -> SecretStr:
+        if not value.get_secret_value():
+            raise ValueError("must not be empty")
+        return value
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        # Environment variables win; config-file values arrive as init kwargs (see load_settings).
+        return (env_settings, init_settings)
+
+    @property
+    def login_username(self) -> str:
+        """SMTP login: S2K_SMTP_USERNAME, or the sender address when unset or empty."""
+        return self.smtp_username or self.sender_email
+
+
+def read_config_file(path: Path) -> dict[str, str]:
+    """Return the S2K_* entries of a config file, read literally (no ${VAR} expansion).
+
+    Raises OSError if the file exists but cannot be read; a missing file gives {}.
+    """
+    if not path.is_file():
+        return {}
+    values = dotenv_values(path, encoding="utf-8", interpolate=False)
+    return {
+        key.upper(): value
+        for key, value in values.items()
+        if value is not None and key.upper().startswith(ENV_PREFIX)
+    }
+
+
+def _describe(error: ValidationError, path: Path) -> str:
+    lines = [f"Invalid configuration (check {path} or your environment variables):"]
+    for item in error.errors():
+        field = str(item["loc"][0]) if item["loc"] else "?"
+        reason = "is required" if item["type"] == "missing" else item["msg"]
+        lines.append(f"  {ENV_PREFIX}{field.upper()}: {reason}")
+    return "\n".join(lines)
+
+
+def load_settings() -> Settings:
+    """Load settings from the environment and config_file_path(), raising ConfigError if invalid."""
+    path = config_file_path()
+    try:
+        file_values: dict[str, Any] = {
+            key.removeprefix(ENV_PREFIX).lower(): value
+            for key, value in read_config_file(path).items()
+        }
+        return Settings(**file_values)
+    except ValidationError as error:
+        raise ConfigError(_describe(error, path)) from None
+    except OSError as error:
+        raise ConfigError(f"Cannot read {path}: {error.strerror or error}") from None

s2k_cli-0.1.0/src/send_2_kindle/constants.py

@@ -0,0 +1,19 @@
+"""Fixed values: Amazon Send to Kindle limits and SMTP defaults."""
+
+from typing import Final
+
+# Formats accepted by Send to Kindle by email (verified 2026-10-05). MOBI is no longer accepted.
+ALLOWED_EXTENSIONS: Final[frozenset[str]] = frozenset(
+    {
+        ".doc", ".docx", ".html", ".htm", ".rtf", ".txt",
+        ".jpeg", ".jpg", ".gif", ".png", ".bmp", ".pdf", ".epub",
+    }
+)  # fmt: skip
+
+# Amazon allows 50 MB per email; decimal megabytes is the conservative reading.
+MAX_EMAIL_SIZE_BYTES: Final[int] = 50_000_000
+
+SMTP_TIMEOUT_SECONDS: Final[float] = 30.0
+
+GMAIL_SMTP_HOST: Final[str] = "smtp.gmail.com"
+GMAIL_APP_PASSWORDS_URL: Final[str] = "https://myaccount.google.com/apppasswords"

s2k_cli-0.1.0/src/send_2_kindle/doctor.py

@@ -0,0 +1,129 @@
+"""Readiness checks for `s2k doctor` and the end of `s2k init`. Never sends email."""
+
+import os
+import platform
+import stat
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+import typer
+
+from send_2_kindle import installed_version
+from send_2_kindle.config import REQUIRED_VARIABLES, config_file_path, load_settings
+from send_2_kindle.errors import ConfigError, SmtpAuthError, SmtpConnectionError
+from send_2_kindle.mailer import KindleMailer
+
+AMAZON_NOTE = (
+    "Amazon cannot be checked without sending. To confirm end to end: s2k send <small-file.txt>"
+)
+
+
+class Status(StrEnum):
+    OK = "✓"
+    WARN = "⚠"
+    FAIL = "✗"
+    SKIP = "-"
+    INFO = "ℹ"  # noqa: RUF001 - intentional "information" symbol, not the letter i
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    status: Status
+    message: str
+
+
+_COLORS: dict[Status, str] = {
+    Status.OK: typer.colors.GREEN,
+    Status.WARN: typer.colors.YELLOW,
+    Status.FAIL: typer.colors.RED,
+}
+
+
+def _display(path: Path) -> str:
+    home = Path.home()
+    return f"~/{path.relative_to(home)}" if path.is_relative_to(home) else str(path)
+
+
+def _skipped(*names: str) -> list[CheckResult]:
+    return [CheckResult(Status.SKIP, f"{name} (not checked)") for name in names]
+
+
+def _config_source() -> list[CheckResult]:
+    path = config_file_path()
+    if path.is_file():
+        results = [CheckResult(Status.OK, f"Config file: {_display(path)}")]
+        if os.name == "posix" and stat.S_IMODE(path.stat().st_mode) & 0o077:
+            results.append(
+                CheckResult(
+                    Status.WARN,
+                    f"Config file is readable by other users → chmod 600 {_display(path)}",
+                )
+            )
+        return results
+    if all(os.environ.get(name) for name in REQUIRED_VARIABLES):
+        return [
+            CheckResult(Status.OK, f"Using environment variables (no file at {_display(path)})")
+        ]
+    return [
+        CheckResult(
+            Status.FAIL,
+            f"No configuration found at {_display(path)} → run `s2k init` in your terminal",
+        )
+    ]
+
+
+def run_checks() -> list[CheckResult]:
+    """Run every readiness check in order; later checks are skipped when one fails."""
+    results = [
+        CheckResult(Status.OK, f"s2k {installed_version()} (Python {platform.python_version()})")
+    ]
+    amazon = CheckResult(Status.INFO, AMAZON_NOTE)
+
+    results.extend(_config_source())
+    if any(result.status is Status.FAIL for result in results):
+        return [*results, *_skipped("Settings", "SMTP connection", "SMTP login"), amazon]
+
+    try:
+        settings = load_settings()
+    except ConfigError as error:
+        results.append(CheckResult(Status.FAIL, str(error)))
+        return [*results, *_skipped("SMTP connection", "SMTP login"), amazon]
+    results.append(
+        CheckResult(
+            Status.OK,
+            f"Settings valid (sender {settings.sender_email} → kindle {settings.kindle_email})",
+        )
+    )
+
+    connected = CheckResult(
+        Status.OK,
+        f"Connected to {settings.smtp_host}:{settings.smtp_port} "
+        f"({settings.smtp_security.upper()})",
+    )
+    try:
+        with KindleMailer(settings):
+            pass
+    except SmtpConnectionError as error:
+        results.append(CheckResult(Status.FAIL, str(error)))
+        results.extend(_skipped("SMTP login"))
+    except SmtpAuthError as error:
+        results.extend([connected, CheckResult(Status.FAIL, str(error))])
+    else:
+        results.extend(
+            [connected, CheckResult(Status.OK, f"Logged in as {settings.login_username}")]
+        )
+    results.append(amazon)
+    return results
+
+
+def report(results: list[CheckResult]) -> int:
+    """Print the results and return the exit code: 0 when nothing failed, else 1."""
+    for result in results:
+        typer.secho(f"{result.status} {result.message}", fg=_COLORS.get(result.status))
+    failures = sum(result.status is Status.FAIL for result in results)
+    if failures:
+        typer.secho(f"Not ready: {failures} problem(s).", fg=typer.colors.RED)
+        return 1
+    typer.secho("Ready.", fg=typer.colors.GREEN)
+    return 0

s2k_cli-0.1.0/src/send_2_kindle/errors.py

@@ -0,0 +1,25 @@
+"""Exceptions raised by s2k. Messages are shown to the user as-is."""
+
+
+class S2KError(Exception):
+    """Base class for every expected s2k error."""
+
+
+class ConfigError(S2KError):
+    """The configuration (.env or environment variables) is missing or invalid."""
+
+
+class FileValidationError(S2KError):
+    """A file cannot be sent (missing, unsupported, empty, unreadable or too large)."""
+
+
+class SmtpConnectionError(S2KError):
+    """The SMTP server cannot be reached or the connection was lost."""
+
+
+class SmtpAuthError(S2KError):
+    """The SMTP server rejected the credentials."""
+
+
+class SendError(S2KError):
+    """The SMTP server rejected one specific message."""

s2k_cli-0.1.0/src/send_2_kindle/mailer.py

@@ -0,0 +1,162 @@
+"""Build Send to Kindle emails and send them over one SMTP session."""
+
+import mimetypes
+import smtplib
+import ssl
+from email.message import EmailMessage
+from pathlib import Path
+from types import TracebackType
+from typing import Self
+
+from send_2_kindle import constants
+from send_2_kindle.config import Settings
+from send_2_kindle.errors import SendError, SmtpAuthError, SmtpConnectionError
+
+
+def build_message(settings: Settings, path: Path) -> EmailMessage:
+    """Return an email to the Kindle address with ``path`` as its only attachment."""
+    message = EmailMessage()
+    message["From"] = settings.sender_email
+    message["To"] = settings.kindle_email
+    message["Subject"] = path.name
+    message.set_content("")
+
+    mime_type, _ = mimetypes.guess_type(path.name)
+    maintype, subtype = (mime_type or "application/octet-stream").split("/", 1)
+    message.add_attachment(
+        path.read_bytes(), maintype=maintype, subtype=subtype, filename=path.name
+    )
+    return message
+
+
+def _text(value: bytes | str) -> str:
+    return value.decode(errors="replace") if isinstance(value, bytes) else value
+
+
+def _auth_failure_message(settings: Settings) -> str:
+    message = f"authentication failed for {settings.login_username} on {settings.smtp_host}"
+    if settings.smtp_host == constants.GMAIL_SMTP_HOST:
+        message += (
+            ". Gmail requires an app password, not your account password: "
+            f"{constants.GMAIL_APP_PASSWORDS_URL}"
+        )
+    return message
+
+
+def _close_quietly(smtp: smtplib.SMTP | None) -> None:
+    if smtp is not None:
+        smtp.close()
+
+
+def _login(smtp: smtplib.SMTP, settings: Settings) -> None:
+    """Log in, reporting any other SMTP refusal of the login as an auth error."""
+    try:
+        smtp.login(settings.login_username, settings.smtp_password.get_secret_value())
+    except (
+        smtplib.SMTPAuthenticationError,
+        smtplib.SMTPNotSupportedError,
+        smtplib.SMTPServerDisconnected,
+    ):
+        raise
+    except smtplib.SMTPException as error:
+        _close_quietly(smtp)
+        raise SmtpAuthError(
+            f"login failed for {settings.login_username} on {settings.smtp_host}: {error}"
+        ) from error
+
+
+class KindleMailer:
+    """One authenticated SMTP session that sends one email per file.
+
+    Use as a context manager: ``with KindleMailer(settings) as mailer: mailer.send(path)``.
+    """
+
+    def __init__(self, settings: Settings) -> None:
+        self._settings = settings
+        self._smtp: smtplib.SMTP | None = None
+
+    def __enter__(self) -> Self:
+        settings = self._settings
+        smtp: smtplib.SMTP | None = None
+        try:
+            if settings.smtp_security == "ssl":
+                smtp = smtplib.SMTP_SSL(
+                    settings.smtp_host,
+                    settings.smtp_port,
+                    timeout=constants.SMTP_TIMEOUT_SECONDS,
+                    context=ssl.create_default_context(),
+                )
+            else:
+                smtp = smtplib.SMTP(
+                    settings.smtp_host,
+                    settings.smtp_port,
+                    timeout=constants.SMTP_TIMEOUT_SECONDS,
+                )
+                smtp.starttls(context=ssl.create_default_context())
+            _login(smtp, settings)
+        except smtplib.SMTPAuthenticationError as error:
+            _close_quietly(smtp)
+            raise SmtpAuthError(_auth_failure_message(settings)) from error
+        except UnicodeEncodeError as error:  # smtplib sends credentials as ASCII
+            _close_quietly(smtp)
+            raise SmtpAuthError(
+                "SMTP username and password must contain only ASCII characters"
+            ) from error
+        except smtplib.SMTPNotSupportedError as error:  # e.g. no STARTTLS or no AUTH
+            _close_quietly(smtp)
+            raise SmtpConnectionError(
+                f"{settings.smtp_host}:{settings.smtp_port} does not support a required feature "
+                f"(check S2K_SMTP_SECURITY and S2K_SMTP_PORT): {error}"
+            ) from error
+        except OSError as error:  # smtplib.SMTPException, timeouts and ssl.SSLError are OSErrors
+            _close_quietly(smtp)
+            raise SmtpConnectionError(
+                f"could not connect to {settings.smtp_host}:{settings.smtp_port}: {error}"
+            ) from error
+        self._smtp = smtp
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        smtp, self._smtp = self._smtp, None
+        if smtp is None:
+            return
+        try:
+            smtp.quit()
+        except OSError:
+            smtp.close()
+
+    def send(self, path: Path) -> None:
+        """Send ``path`` as one email.
+
+        Raises SendError when only this message failed, and SmtpConnectionError when the
+        session is lost.
+        """
+        if self._smtp is None:
+            raise RuntimeError("KindleMailer.send() must be called inside a 'with' block")
+        try:
+            message = build_message(self._settings, path)
+        except OSError as error:
+            raise SendError(f"could not read file: {error}") from error
+        try:
+            self._smtp.send_message(message)
+        except smtplib.SMTPServerDisconnected as error:
+            raise SmtpConnectionError(f"connection lost: {error}") from error
+        except smtplib.SMTPRecipientsRefused as error:
+            details = "; ".join(
+                f"{address}: {code} {_text(reply)}"
+                for address, (code, reply) in error.recipients.items()
+            )
+            raise SendError(f"recipient refused: {details}") from error
+        except smtplib.SMTPResponseException as error:
+            raise SendError(
+                f"server rejected the message: {error.smtp_code} {_text(error.smtp_error)}"
+            ) from error
+        except smtplib.SMTPException as error:
+            raise SendError(f"server rejected the message: {error}") from error
+        except OSError as error:  # network errors and timeouts after login
+            raise SmtpConnectionError(f"connection lost: {error}") from error

s2k_cli-0.1.0/src/send_2_kindle/main.py

@@ -0,0 +1,121 @@
+"""Command-line entry point: ``s2k FILE...``."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from send_2_kindle import installed_version
+from send_2_kindle.config import load_settings
+from send_2_kindle.doctor import report, run_checks
+from send_2_kindle.errors import (
+    ConfigError,
+    FileValidationError,
+    SendError,
+    SmtpAuthError,
+    SmtpConnectionError,
+)
+from send_2_kindle.mailer import KindleMailer
+from send_2_kindle.validation import validate_file
+from send_2_kindle.wizard import run_wizard
+
+AMAZON_NOTE = (
+    "Note: Amazon may still reject a sent file (e.g. sender not approved); it will email you if so."
+)
+
+# Never show local variables in tracebacks: they could include the SMTP password.
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False, no_args_is_help=True)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"s2k {installed_version()}")
+        raise typer.Exit()
+
+
+@app.callback()
+def cli(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_print_version, is_eager=True, help="Show the version and exit."
+        ),
+    ] = False,
+) -> None:
+    """Send local files to your Kindle through the Send to Kindle email service."""
+
+
+@dataclass
+class Outcome:
+    path: Path
+    sent: bool = False
+    reason: str = "not sent"
+
+
+@app.command()
+def send(
+    files: Annotated[
+        list[Path],
+        typer.Argument(help="Files to send (pdf, epub, docx, txt, ...).", show_default=False),
+    ],
+) -> None:
+    """Send files to your Kindle, one email per file."""
+    try:
+        settings = load_settings()
+    except ConfigError as error:
+        typer.secho(str(error), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2) from None
+
+    outcomes = [Outcome(path) for path in files]
+    pending: list[Outcome] = []
+    for outcome in outcomes:
+        try:
+            validate_file(outcome.path)
+        except FileValidationError as error:
+            outcome.reason = str(error)
+        else:
+            pending.append(outcome)
+
+    if pending:
+        try:
+            with KindleMailer(settings) as mailer:
+                for outcome in pending:
+                    try:
+                        mailer.send(outcome.path)
+                    except SendError as error:
+                        outcome.reason = str(error)
+                    else:
+                        outcome.sent = True
+        except (SmtpConnectionError, SmtpAuthError) as error:
+            typer.secho(f"Error: {error}", fg=typer.colors.RED, err=True)
+
+    _print_report(outcomes)
+    if not all(outcome.sent for outcome in outcomes):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def doctor() -> None:
+    """Check that s2k is configured and can log in to your SMTP server (sends nothing)."""
+    raise typer.Exit(code=report(run_checks()))
+
+
+@app.command()
+def init() -> None:
+    """Interactive setup that writes your config file. Run it in your own terminal."""
+    raise typer.Exit(code=run_wizard())
+
+
+def _print_report(outcomes: list[Outcome]) -> None:
+    width = max(len(str(outcome.path)) for outcome in outcomes)
+    for outcome in outcomes:
+        name = str(outcome.path).ljust(width)
+        if outcome.sent:
+            typer.secho(f"✓ {name}  sent", fg=typer.colors.GREEN)
+        else:
+            typer.secho(f"✗ {name}  {outcome.reason}", fg=typer.colors.RED)
+    sent = sum(outcome.sent for outcome in outcomes)
+    typer.echo(f"{sent} sent, {len(outcomes) - sent} failed")
+    if sent:
+        typer.echo(AMAZON_NOTE)

s2k_cli-0.1.0/src/send_2_kindle/validation.py

@@ -0,0 +1,41 @@
+"""Local checks that decide whether a file can be sent to Kindle."""
+
+import os
+import stat
+from pathlib import Path
+
+from send_2_kindle import constants
+from send_2_kindle.errors import FileValidationError
+
+
+def _megabytes(size: int) -> float:
+    return size / 1_000_000
+
+
+def validate_file(path: Path) -> None:
+    """Raise FileValidationError with a user-facing reason if ``path`` cannot be sent."""
+    # stat() tells "missing" apart from "can't reach it" (Path.exists() reports both as False).
+    try:
+        info = path.stat()
+    except FileNotFoundError:
+        raise FileValidationError("file not found") from None
+    except PermissionError:
+        raise FileValidationError("file is not readable") from None
+    if not stat.S_ISREG(info.st_mode):
+        raise FileValidationError("not a regular file")
+
+    extension = path.suffix.lower()
+    if extension not in constants.ALLOWED_EXTENSIONS:
+        allowed = ", ".join(sorted(constants.ALLOWED_EXTENSIONS))
+        raise FileValidationError(
+            f"unsupported extension '{extension or '(none)'}'; allowed: {allowed}"
+        )
+
+    size = info.st_size
+    if size == 0:
+        raise FileValidationError("file is empty")
+    if not os.access(path, os.R_OK):
+        raise FileValidationError("file is not readable")
+    if size > constants.MAX_EMAIL_SIZE_BYTES:
+        limit = _megabytes(constants.MAX_EMAIL_SIZE_BYTES)
+        raise FileValidationError(f"file exceeds {limit:g} MB ({_megabytes(size):.1f} MB)")

s2k_cli-0.1.0/src/send_2_kindle/wizard.py

@@ -0,0 +1,139 @@
+"""`s2k init`: interactive wizard that writes the user's config file."""
+
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import typer
+from pydantic import EmailStr, TypeAdapter, ValidationError
+
+from send_2_kindle import constants
+from send_2_kindle.config import (
+    SmtpHost,
+    SmtpPort,
+    SmtpSecurity,
+    config_file_path,
+    read_config_file,
+)
+from send_2_kindle.doctor import report, run_checks
+
+INTRO = """\
+s2k init: configure Send to Kindle by email.
+
+You will need:
+  - Your Send to Kindle address: Amazon > Manage Your Content and Devices > Preferences >
+    Personal Document Settings.
+  - The email you send from must be on the "Approved Personal Document E-mail List" (same page).
+  - Gmail: an app password, not your account password: {url}
+"""
+HEADER = "# s2k configuration, written by `s2k init`. Keep it private (chmod 600).\n"
+
+_EMAIL: TypeAdapter[Any] = TypeAdapter(EmailStr)
+_HOST: TypeAdapter[Any] = TypeAdapter(SmtpHost)
+_PORT: TypeAdapter[Any] = TypeAdapter(SmtpPort)
+_SECURITY: TypeAdapter[Any] = TypeAdapter(SmtpSecurity)
+
+
+def _is_interactive() -> bool:
+    return sys.stdin.isatty()
+
+
+def _quote(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def write_config(path: Path, values: dict[str, str]) -> None:
+    """Atomically write ``values`` as KEY="value" lines to ``path`` (mode 600, new dirs 700)."""
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    content = HEADER + "".join(f"{key}={_quote(value)}\n" for key, value in values.items())
+    fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=".config.env.")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+        os.chmod(temp_name, 0o600)
+        os.replace(temp_name, path)
+    except BaseException:
+        Path(temp_name).unlink(missing_ok=True)
+        raise
+
+
+def _read_existing(path: Path) -> dict[str, str]:
+    try:
+        return read_config_file(path)
+    except OSError:
+        return {}
+
+
+def _ask(text: str, adapter: TypeAdapter[Any], default: str | None) -> str:
+    while True:
+        answer = str(typer.prompt(text, default=default, type=str)).strip()
+        try:
+            adapter.validate_python(answer)
+        except ValidationError as error:
+            typer.secho(f"  {error.errors()[0]['msg']}", fg=typer.colors.YELLOW)
+        else:
+            return answer
+
+
+def _ask_password(has_current: bool) -> str | None:
+    """Return the new password, or None to keep the current one."""
+    if has_current:
+        answer = typer.prompt(
+            "SMTP password (empty keeps the current one)",
+            default="",
+            hide_input=True,
+            show_default=False,
+        )
+        return str(answer) or None
+    return str(typer.prompt("SMTP password", hide_input=True))
+
+
+def _collect(current: dict[str, str]) -> dict[str, str]:
+    values = {
+        "S2K_KINDLE_EMAIL": _ask("Send to Kindle address", _EMAIL, current.get("S2K_KINDLE_EMAIL")),
+        "S2K_SENDER_EMAIL": _ask("Email you send from", _EMAIL, current.get("S2K_SENDER_EMAIL")),
+        "S2K_SMTP_HOST": _ask(
+            "SMTP server", _HOST, current.get("S2K_SMTP_HOST", constants.GMAIL_SMTP_HOST)
+        ),
+        "S2K_SMTP_PORT": _ask("SMTP port", _PORT, current.get("S2K_SMTP_PORT", "587")),
+        "S2K_SMTP_SECURITY": _ask(
+            "Security (starttls/ssl)", _SECURITY, current.get("S2K_SMTP_SECURITY", "starttls")
+        ),
+    }
+    password = _ask_password(bool(current.get("S2K_SMTP_PASSWORD")))
+    values["S2K_SMTP_PASSWORD"] = password if password is not None else current["S2K_SMTP_PASSWORD"]
+    if current.get("S2K_SMTP_USERNAME"):
+        values["S2K_SMTP_USERNAME"] = current["S2K_SMTP_USERNAME"]
+    return values
+
+
+def run_wizard() -> int:
+    """Run the interactive setup and return the process exit code."""
+    if not _is_interactive():
+        typer.secho(
+            "s2k init is interactive; run it in your own terminal.", fg=typer.colors.RED, err=True
+        )
+        return 2
+    path = config_file_path()
+    typer.echo(INTRO.format(url=constants.GMAIL_APP_PASSWORDS_URL))
+    try:
+        values = _collect(_read_existing(path))
+    except typer.Abort:
+        typer.secho("Aborted; configuration not changed.", fg=typer.colors.RED, err=True)
+        return 1
+    try:
+        write_config(path, values)
+    except OSError as error:
+        typer.secho(
+            f"Cannot write {path}: {error.strerror or error}", fg=typer.colors.RED, err=True
+        )
+        return 2
+    typer.echo(f"Saved {path} (permissions 600)")
+    try:
+        run_now = typer.confirm("Run checks now?", default=True)
+    except typer.Abort:
+        return 0
+    return report(run_checks()) if run_now else 0