userdir-publish 0.0.1__py3-none-any.whl

userdir_publish/__init__.py

@@ -0,0 +1 @@
+"""Publish a static website to a personal web directory served by Apache's ``mod_userdir``."""

userdir_publish/cli.py

@@ -0,0 +1,118 @@
+"""Command-line interface for ``userdir-publish``."""
+
+import shlex
+import subprocess
+import sys
+from dataclasses import asdict
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from userdir_publish.config import ConfigError, load_settings
+from userdir_publish.publish import PublishError, publish, use_ssh
+
+app = typer.Typer()
+console = Console(soft_wrap=True)
+"""Prints long paths on one line, so that they can be copied."""
+
+RESUME_HINT = "Rerun to resume: files that were already copied are not sent again."
+
+
+@app.command()
+def main(  # ruff: ignore[too-many-arguments]
+    source: Annotated[
+        str | None,
+        typer.Argument(help="Directory with the built website.", show_default=False),
+    ] = None,
+    *,
+    host: Annotated[
+        str | None, typer.Option(help="SSH host that serves the pages.")
+    ] = None,
+    user: Annotated[
+        str | None, typer.Option(help="Login name on the host.", show_default=False)
+    ] = None,
+    web_root: Annotated[
+        str | None,
+        typer.Option(help="Web directory, may contain {user}.", show_default=False),
+    ] = None,
+    subdirectory: Annotated[
+        str | None,
+        typer.Option(help="Subdirectory of the web root.", show_default=False),
+    ] = None,
+    keep: Annotated[
+        list[str] | None,
+        typer.Option(help="rsync pattern under the target that is never deleted."),
+    ] = None,
+    permissions: Annotated[
+        str | None,
+        typer.Option(
+            help="private, group-writable, none, or an rsync --chmod spec.",
+            show_default=False,
+        ),
+    ] = None,
+    transport: Annotated[
+        str | None,
+        typer.Option(help="auto, local, or ssh.", show_default=False),
+    ] = None,
+    dry_run: Annotated[
+        bool, typer.Option(help="Show what would change without copying.")
+    ] = False,
+    progress: Annotated[
+        bool | None,
+        typer.Option(
+            help="Show the transfer progress. Default: if the output is a terminal.",
+            show_default=False,
+        ),
+    ] = None,
+    show_config: Annotated[
+        bool, typer.Option(help="Print the merged configuration and exit.")
+    ] = False,
+) -> None:
+    r"""Publish a built website to a web directory served by Apache's mod_userdir.
+
+    Options are read from the user config, then \[tool.userdir-publish] in
+    pyproject.toml, then these flags, each overriding the previous.
+    """
+    cli = {
+        "source": source,
+        "host": host,
+        "user": user,
+        "web_root": web_root,
+        "subdirectory": subdirectory,
+        "keep": keep or None,
+        "permissions": permissions,
+        "transport": transport,
+    }
+    if progress is None:
+        progress = sys.stdout.isatty()
+    try:
+        settings = load_settings(cli)
+        if show_config:
+            for key, value in asdict(settings).items():
+                console.print(f"{key} = {value!r}")
+            console.print(f"target = {settings.target!r}")
+            return
+        command = publish(settings, dry_run=dry_run, progress=progress)
+    except (ConfigError, PublishError) as exc:
+        console.print(f"[red]{exc}")
+        raise typer.Exit(code=1) from exc
+    except subprocess.CalledProcessError as exc:
+        console.print(f"[red]rsync failed: {shlex.join(command_of(exc))}")
+        console.print(f"[yellow]{RESUME_HINT}")
+        raise typer.Exit(code=exc.returncode) from exc
+    except KeyboardInterrupt as exc:
+        console.print(f"[red]Interrupted. {RESUME_HINT}")
+        raise typer.Exit(code=130) from exc
+    if dry_run:
+        console.print(f"[yellow]Dry run: {shlex.join(command)}")
+        return
+    destination = f"{settings.host}:" if use_ssh(settings) else ""
+    console.print(f"[green]Published to {destination}{settings.target}")
+    url = settings.resolved_url()
+    if url is not None:
+        console.print(f"[green]{url}")
+
+
+def command_of(exc: subprocess.CalledProcessError) -> list[str]:
+    return [str(arg) for arg in exc.cmd]

userdir_publish/config.py

@@ -0,0 +1,299 @@
+"""Layered configuration: defaults, user config, project config, and CLI flags.
+
+Each layer overrides the one before it. For the login name, a matching host entry in the
+user config overrides the project config, while the CLI takes precedence over both. The
+``USER`` environment variable supplies the fallback. Exact host entries take precedence
+over patterns; otherwise the first matching pattern in file order applies.
+"""
+
+# cspell:ignore rwxs
+
+import os
+import re
+import tomllib
+from dataclasses import dataclass, field, fields
+from fnmatch import fnmatchcase
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal, get_args
+
+TOOL_NAME = "userdir-publish"
+
+Transport = Literal["auto", "local", "ssh"]
+"""How to reach the web directory, see `Settings.transport`."""
+TRANSPORTS: tuple[Transport, ...] = get_args(Transport)
+
+PermissionPreset = Literal["private", "group-writable", "none"]
+"""Named permission settings, see `Settings.permissions`."""
+
+PERMISSION_PRESETS: dict[PermissionPreset, str | None] = {
+    "private": "Dg-rwx,Do=x,Fg-rwx,Fo=r",
+    "group-writable": "Dg=rwxs,Do=x,Fg=rw,Fo=r",
+    "none": None,
+}
+"""Named arguments for ``rsync --chmod``, see `Settings.permissions`."""
+
+_CHMOD_CLAUSE = r"[DF]?(?:[0-7]{3,4}|[ugoa]*(?:[-+=][rwxXst]*)+)"
+CHMOD_PATTERN = rf"^{_CHMOD_CLAUSE}(?:,{_CHMOD_CLAUSE})*$"
+"""Comma-separated clauses accepted by ``rsync --chmod``, such as ``D2775,Fg-w``.
+
+`Settings.permissions` must be a key of `PERMISSION_PRESETS` or match this pattern.
+"""
+
+
+class ConfigError(ValueError):
+    """Raised when a configuration value is invalid."""
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Merged and validated configuration for one publication.
+
+    Create it with `load_settings` rather than directly, so that all configuration
+    layers are applied and the values are validated.
+    """
+
+    source: str | None = field(
+        default=None,
+        metadata={"examples": ["docs/_build/html"]},
+    )
+    """Directory of the built website, relative to the directory with ``pyproject.toml``.
+
+    The first command-line argument overrides it.
+    """
+    host: str | None = field(default=None, metadata={"examples": ["web.example.edu"]})
+    """SSH host that serves the pages. Without it, only local publishing is possible."""
+    web_root: str = "~/public_html"
+    """Web directory on the server. ``{user}`` is replaced by the login name.
+
+    A leading ``~`` means the home directory of the login on the server.
+    """
+    subdirectory: str = ""
+    """Subdirectory of the web root that this project owns. Empty means the web root.
+
+    Files in it that are not in the build are deleted.
+    """
+    keep: tuple[str, ...] = ()
+    """``rsync`` filter patterns, relative to the target, for files that are never deleted.
+
+    For example, ``/*/`` keeps all top-level directories.
+    """
+    permissions: PermissionPreset | str = field(
+        default="private",
+        metadata={"pattern": CHMOD_PATTERN},
+    )
+    """Permissions of the published files, as a preset or a raw ``rsync --chmod`` spec.
+
+    ``private`` hides the files from group members, ``group-writable`` lets the group
+    maintain a shared page, and ``none`` keeps the local modes.
+    """
+    transport: Transport = "auto"
+    """How to reach the web directory.
+
+    ``auto`` uses SSH if `host` is set and the target does not exist on this machine.
+    """
+    htaccess_source: str | None = field(default=None, metadata={"examples": ["docs"]})
+    """Directory, relative to the project root, whose ``.htaccess`` files the build must contain.
+
+    Publishing is refused if a build lacks one of them or contains an outdated copy.
+    """
+    url: str | None = field(
+        default=None,
+        metadata={"examples": ["https://web.example.edu/~{user}/{subdirectory}/"]},
+    )
+    """Address printed after publishing. ``{user}`` and ``{subdirectory}`` are replaced.
+
+    Defaults to ``https://{host}/~{user}/{subdirectory}/`` if `host` is set.
+    """
+    user: str | None = field(default=None, metadata={"examples": ["jdoe"]})
+    """Login name on the host. Defaults to the ``USER`` environment variable."""
+    _project_root: Path = field(default=Path(), repr=False)
+
+    @property
+    def login(self) -> str:
+        """`user`, or the ``USER`` environment variable if it is not set.
+
+        Raises:
+            ConfigError: If neither is set.
+        """
+        user = self.user or os.getenv("USER")
+        if not user:
+            msg = "Could not determine the login name, set it with --user"
+            raise ConfigError(msg)
+        return user
+
+    @property
+    def chmod(self) -> str | None:
+        """`permissions` as ``rsync --chmod`` spec, or `None` to leave them as is."""
+        return PERMISSION_PRESETS.get(self.permissions, self.permissions)
+
+    @property
+    def source_dir(self) -> Path:
+        """`source` resolved against the project root.
+
+        Raises:
+            ConfigError: If `source` is not set.
+        """
+        if self.source is None:
+            msg = "No source directory given, pass it as argument or set source"
+            raise ConfigError(msg)
+        return self._project_root / self.source
+
+    @property
+    def htaccess_dir(self) -> Path | None:
+        """`htaccess_source` resolved against the project root."""
+        if self.htaccess_source is None:
+            return None
+        return self._project_root / self.htaccess_source
+
+    @property
+    def target(self) -> str:
+        """`web_root` with ``{user}`` replaced, followed by `subdirectory`.
+
+        A leading ``~`` is kept, so the path is valid on the host and on this machine.
+
+        Raises:
+            ConfigError: If the web root is empty.
+        """
+        root = self.web_root.format(user=self.login).rstrip("/")
+        if not root:
+            msg = "The web root may not be empty"
+            raise ConfigError(msg)
+        if not self.subdirectory:
+            return root
+        return f"{root}/{self.subdirectory}"
+
+    @property
+    def remote_target(self) -> str:
+        """Target path for SSH, where a leading ``~/`` means the login's home."""
+        return self.target.removeprefix("~/")
+
+    def resolved_url(self) -> str | None:
+        """`url` with ``{user}`` and ``{subdirectory}`` replaced.
+
+        Without `url`, the address is derived from `host`, or `None` if that is unset.
+        """
+        if self.url is not None:
+            return self.url.format(user=self.login, subdirectory=self.subdirectory)
+        if self.host is None:
+            return None
+        path = "/".join(part for part in (f"~{self.login}", self.subdirectory) if part)
+        return f"https://{self.host}/{path}/"
+
+
+def load_settings(
+    cli: dict[str, Any] | None = None,
+    *,
+    project_root: Path | None = None,
+    user_config: Path | None = None,
+) -> Settings:
+    """Merge all configuration layers into one `Settings` object.
+
+    Entries of *cli* that are `None` count as not given. *project_root* is the directory
+    with the ``pyproject.toml`` that holds the project configuration and defaults to the
+    nearest such directory at or above the working directory. *user_config* defaults to
+    `user_config_path`.
+
+    Raises:
+        ConfigError: If an option is unknown or a value is invalid.
+    """
+    if project_root is None:
+        project_root = _find_project_root(Path.cwd())
+    if user_config is None:
+        user_config = user_config_path()
+    user_table = _read_table(user_config, key=None)
+    project_table = _read_table(project_root / "pyproject.toml", key=TOOL_NAME)
+    cli = {k: v for k, v in (cli or {}).items() if v is not None}
+    hosts = user_table.pop("hosts", {})
+    merged = {**user_table, **project_table}
+    host = cli.get("host", merged.get("host"))
+    if host is not None:
+        if host in hosts:
+            merged.update(hosts[host])
+        else:
+            for pattern, options in hosts.items():
+                if fnmatchcase(host, pattern):
+                    merged.update(options)
+                    break
+    merged.update(cli)
+    settings = _to_settings(merged, project_root)
+    _validate(settings)
+    return settings
+
+
+def _find_project_root(start: Path) -> Path:
+    for directory in (start, *start.parents):
+        if (directory / "pyproject.toml").is_file():
+            return directory
+    return start
+
+
+def user_config_path() -> Path:
+    """Locate the user configuration file.
+
+    This is :file:`$XDG_CONFIG_HOME/userdir-publish.toml` if it exists, otherwise
+    :file:`$XDG_CONFIG_HOME/userdir-publish/config.toml`. ``XDG_CONFIG_HOME`` defaults
+    to :file:`~/.config`.
+
+    Raises:
+        ConfigError: If both files exist.
+    """
+    config_home = Path(os.getenv("XDG_CONFIG_HOME") or Path.home() / ".config")
+    nested = config_home / TOOL_NAME / "config.toml"
+    flat = config_home / f"{TOOL_NAME}.toml"
+    if nested.is_file() and flat.is_file():
+        msg = f"Found both {nested} and {flat}; keep only one"
+        raise ConfigError(msg)
+    return flat if flat.is_file() else nested
+
+
+def _read_table(path: Path, key: str | None) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    with path.open("rb") as stream:
+        table = tomllib.load(stream)
+    if key is not None:
+        table = table.get("tool", {}).get(key, {})
+    normalized = _normalize_keys(table)
+    if "hosts" in normalized:
+        normalized["hosts"] = {
+            host: _normalize_keys(options)
+            for host, options in normalized["hosts"].items()
+        }
+    return normalized
+
+
+def _normalize_keys(table: dict[str, Any]) -> dict[str, Any]:
+    return {k.replace("-", "_"): v for k, v in table.items()}
+
+
+def _to_settings(table: dict[str, Any], project_root: Path) -> Settings:
+    known = {f.name for f in fields(Settings) if not f.name.startswith("_")}
+    unknown = sorted(set(table) - known)
+    if unknown:
+        msg = f"Unknown {TOOL_NAME} options: {', '.join(unknown)}"
+        raise ConfigError(msg)
+    if "keep" in table:
+        table["keep"] = tuple(table["keep"])
+    return Settings(**table, _project_root=project_root)
+
+
+def _validate(settings: Settings) -> None:
+    if settings.transport not in TRANSPORTS:
+        msg = f"transport must be one of {', '.join(TRANSPORTS)}"
+        raise ConfigError(msg)
+    if settings.transport == "ssh" and not settings.host:
+        msg = "Publishing over SSH requires a host"
+        raise ConfigError(msg)
+    subdirectory = PurePosixPath(settings.subdirectory)
+    if subdirectory.is_absolute() or ".." in subdirectory.parts:
+        msg = f"subdirectory must be relative to the web root: {settings.subdirectory}"
+        raise ConfigError(msg)
+    if settings.permissions not in PERMISSION_PRESETS and not re.match(
+        CHMOD_PATTERN, settings.permissions
+    ):
+        msg = f"permissions is neither a preset nor an rsync --chmod spec: {settings.permissions!r}"
+        raise ConfigError(msg)
+    if any(c.isspace() for c in settings.login) or "@" in settings.login:
+        msg = f"Invalid login name: {settings.login!r}"
+        raise ConfigError(msg)
+    _ = settings.target  # raises if the web root is empty

userdir_publish/publish.py

@@ -0,0 +1,235 @@
+"""Validate a built website and copy it to the web directory with rsync."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+if TYPE_CHECKING:
+    from userdir_publish.config import Settings
+
+
+_SYMLINK_EXIT = 3
+
+
+class PublishError(RuntimeError):
+    """Raised when the website cannot be published safely."""
+
+
+def validate_build(settings: Settings) -> None:
+    """Check that the build can be published.
+
+    The build must contain an ``index.html``. If `~.Settings.htaccess_source` is set,
+    every ``.htaccess`` file under it must appear unchanged at the same relative path in
+    the build. Hidden directories, the build itself, and files ignored by Git are not
+    searched.
+
+    Raises:
+        PublishError: If a check fails.
+    """
+    source = settings.source_dir
+    if not (source / "index.html").is_file():
+        msg = f"The build in {source} has no index.html"
+        raise PublishError(msg)
+    rules_dir = settings.htaccess_dir
+    if rules_dir is None:
+        return
+    for rules in _access_rules(rules_dir):
+        if rules.is_relative_to(source):
+            continue
+        built = source / rules.relative_to(rules_dir)
+        if not built.is_file() or built.read_bytes() != rules.read_bytes():
+            msg = f"The build is missing the current access rules: {built}"
+            raise PublishError(msg)
+
+
+def _access_rules(directory: Path) -> Iterator[Path]:
+    """Find the ``.htaccess`` files under *directory*, skipping hidden directories.
+
+    In a Git work tree, files that Git ignores are skipped as well.
+    """
+    tracked = _git_access_rules(directory)
+    if tracked is not None:
+        yield from tracked
+        return
+    for root, dirs, files in os.walk(directory):
+        dirs[:] = [d for d in dirs if not d.startswith(".")]
+        if ".htaccess" in files:
+            yield Path(root, ".htaccess")
+
+
+def _git_access_rules(directory: Path) -> list[Path] | None:
+    """List the ``.htaccess`` files that Git does not ignore.
+
+    Returns `None` outside a Git work tree, or if Git ignores *directory* itself, such
+    as a project inside a home directory that is tracked with Git.
+    """
+    git = shutil.which("git")
+    if git is None:
+        return None
+    ignored = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+        [git, "check-ignore", "--quiet", "."],
+        cwd=directory,
+        capture_output=True,
+        check=False,
+    )
+    if ignored.returncode != 1:
+        return None
+    result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+        [
+            git,
+            "ls-files",
+            "-z",
+            "--cached",
+            "--others",
+            "--exclude-standard",
+            "--",
+            ":(glob)**/.htaccess",
+        ],
+        cwd=directory,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    return [
+        directory / name
+        for name in result.stdout.split("\0")
+        if name and not any(part.startswith(".") for part in Path(name).parent.parts)
+    ]
+
+
+def use_ssh(settings: Settings) -> bool:
+    """Decide whether to publish over SSH.
+
+    With ``transport = "auto"``, SSH is used when a host is set and the target directory
+    does not exist on this machine.
+    """
+    if settings.transport == "auto":
+        if settings.host is None:
+            return False
+        return not Path(settings.target).expanduser().is_dir()
+    return settings.transport == "ssh"
+
+
+def rsync_command(
+    settings: Settings, *, ssh: bool, dry_run: bool = False, progress: bool = False
+) -> list[str]:
+    """Build the rsync command that mirrors the build to the target.
+
+    The command passes ``--delete``, so files in the target that are not in the build
+    are removed, except those matched by `~.Settings.keep`. Unless *dry_run* is set, a
+    local target directory is created, and over SSH the remote target is created by the
+    command itself. With *progress*, rsync reports the overall transfer progress.
+    """
+    command = [_executable("rsync"), "--recursive", "--links", "--times", "--delete"]
+    command.extend(_mkpath_arguments(settings, ssh=ssh, dry_run=dry_run))
+    if settings.chmod is not None:
+        command.extend(["--perms", f"--chmod={settings.chmod}"])
+    command.extend(f"--filter=P {pattern}" for pattern in settings.keep)
+    if dry_run:
+        command.extend(["--dry-run", "--itemize-changes"])
+    elif progress:
+        command.append("--info=progress2")
+    command.append(f"{settings.source_dir}/")
+    if ssh:
+        command.append(f"{settings.login}@{settings.host}:{settings.remote_target}/")
+    else:
+        command.append(f"{Path(settings.target).expanduser()}/")
+    return command
+
+
+def _refuse_symlink(settings: Settings, *, ssh: bool) -> None:
+    """Refuse a symlinked target, because it may point outside the web root."""
+    if ssh:
+        target = shlex.quote(settings.remote_target)
+        result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+            [
+                _executable("ssh"),
+                f"{settings.login}@{settings.host}",
+                f"if [ -L {target} ]; then exit {_SYMLINK_EXIT}; fi",
+            ],
+            check=False,
+        )
+        if result.returncode not in {0, _SYMLINK_EXIT}:
+            msg = f"Could not inspect {settings.remote_target} on {settings.host}"
+            raise PublishError(msg)
+        is_symlink = result.returncode == _SYMLINK_EXIT
+    else:
+        is_symlink = Path(settings.target).expanduser().is_symlink()
+    if is_symlink:
+        msg = f"Refusing to publish to a symlink: {settings.target}"
+        raise PublishError(msg)
+
+
+def _mkpath_arguments(settings: Settings, *, ssh: bool, dry_run: bool) -> list[str]:
+    """Create the parent directories of the target, like ``rsync --mkpath``.
+
+    ``--mkpath`` requires rsync 3.2.3 or newer on both ends, which older servers lack.
+    Over SSH, the directories are therefore created by the remote command that starts
+    rsync. Once all servers run rsync 3.2.3 or newer, return ``["--mkpath"]`` instead.
+    """
+    if dry_run:
+        return []
+    if ssh:
+        target = shlex.quote(settings.remote_target)
+        return [f"--rsync-path=mkdir -p -- {target} && rsync"]
+    Path(settings.target).expanduser().mkdir(parents=True, exist_ok=True)
+    return []
+
+
+def publish(
+    settings: Settings, *, dry_run: bool = False, progress: bool = False
+) -> list[str]:
+    """Copy the build to the target and return the rsync command that was run.
+
+    A dry run still validates the build and refuses a symlinked target, but copies
+    nothing and creates no directories.
+
+    Raises:
+        PublishError: If the build is invalid or the target is a symlink.
+        subprocess.CalledProcessError: If rsync fails.
+    """
+    validate_build(settings)
+    ssh = use_ssh(settings)
+    _refuse_symlink(settings, ssh=ssh)
+    if settings.chmod is not None and is_openrsync():
+        msg = (
+            "The rsync in PATH is openrsync, which ignores --chmod, so the published"
+            " files would not get the configured permissions. Install GNU rsync, for"
+            " instance with 'brew install rsync' on macOS, or set permissions to 'none'."
+        )
+        raise PublishError(msg)
+    command = rsync_command(settings, ssh=ssh, dry_run=dry_run, progress=progress)
+    subprocess.run(command, check=True)  # ruff: ignore[subprocess-without-shell-equals-true]
+    return command
+
+
+def is_openrsync() -> bool:
+    """Check whether the rsync in PATH is openrsync, the default rsync of macOS.
+
+    openrsync accepts ``--chmod`` but silently leaves the permissions unchanged.
+    """
+    result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true]
+        [_executable("rsync"), "--version"],
+        capture_output=True,
+        check=False,
+        text=True,
+    )
+    return "openrsync" in result.stdout + result.stderr
+
+
+def _executable(name: str) -> str:
+    path = shutil.which(name)
+    if path is None:
+        msg = f"{name} executable not found in PATH"
+        raise PublishError(msg)
+    return path

userdir_publish/version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

userdir_publish-0.0.1.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: userdir-publish
+Version: 0.0.1
+Summary: Publish a static website to a personal web directory served by Apache's mod_userdir
+Author: Remco de Boer
+License-Expression: MIT
+Project-URL: Changelog, https://github.com/RUB-EP1/userdir-publish/releases
+Project-URL: Documentation, https://rub-ep1.github.io/userdir-publish
+Project-URL: Homepage, https://rub-ep1.github.io/userdir-publish
+Project-URL: Issues, https://github.com/RUB-EP1/userdir-publish/issues
+Project-URL: Source, https://github.com/RUB-EP1/userdir-publish
+Keywords: apache,mod_userdir,rsync,static-site
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich
+Requires-Dist: typer
+Dynamic: license-file
+
+<!-- cspell:ignore pipx -->
+
+# userdir-publish
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/license/MIT)
+[![PyPI package](https://img.shields.io/pypi/v/userdir-publish)](https://pypi.org/project/userdir-publish)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/userdir-publish)](https://pypi.org/project/userdir-publish)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/RUB-EP1/userdir-publish/main.svg)](https://results.pre-commit.ci/latest/github/RUB-EP1/userdir-publish/main)
+[![CI status](https://github.com/RUB-EP1/userdir-publish/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RUB-EP1/userdir-publish/actions/workflows/ci.yml?query=branch%3Amain)
+[![Test coverage](https://codecov.io/gh/RUB-EP1/userdir-publish/branch/main/graph/badge.svg)](https://app.codecov.io/gh/RUB-EP1/userdir-publish)
+[![Spelling checked](https://img.shields.io/badge/cspell-checked-brightgreen.svg)](https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)
+
+`userdir-publish` copies a built static website to a personal web directory, such as `https://web.example.edu/~jdoe/`, that Apache serves with [`mod_userdir`](https://httpd.apache.org/docs/current/mod/mod_userdir.html). It uses [`rsync`](https://rsync.samba.org), either over [SSH](https://www.openssh.org) or to a local path when the web directory is mounted or you are logged in on the server. It removes stale files, sets permissions the web server can read, and refuses to publish a build that lacks `index.html` or the current `.htaccess` rules.
+
+## Installation
+
+The tool requires `rsync` on your machine and on the server. On macOS, install GNU `rsync` (for instance with `brew install rsync`), because the built-in `openrsync` ignores the permission settings. Install it from [PyPI](https://pypi.org/project/userdir-publish):
+
+```bash
+uv tool install userdir-publish
+```
+
+or with `pipx install userdir-publish`. Then run `userdir-publish --help`.
+
+## Documentation
+
+See [rub-ep1.github.io/userdir-publish](https://rub-ep1.github.io/userdir-publish) for other installation methods, configuration, group pages, and task runner integration.

userdir_publish-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+userdir_publish/__init__.py,sha256=iWmEy4wmlFcK6nkFfv1jhd6ROgemIa4osLM29fSgcbM,95
+userdir_publish/cli.py,sha256=fdJGeTVqoB8b6rqBSSUejNtPQBy-qjNP4Clhp_BZ1Ec,4017
+userdir_publish/config.py,sha256=wFYU_UUSNV32qwn9Zgqetwi3zRIEwpulJ1lhHbxP0RY,11143
+userdir_publish/publish.py,sha256=ZphRqalDhUMuiKfbRak7oIfeBNCtYmfmC8mtAuiMIaA,8329
+userdir_publish/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+userdir_publish/version.py,sha256=8OsTLsIVB9D0HdPTmt5rVwyVUBe9xTVGkRslXicxzkM,520
+userdir_publish-0.0.1.dist-info/licenses/LICENSE,sha256=1gDxzuKGXePQxIISDLPyw9-YR2_Qd8RCeYjXYeIBKqg,1064
+userdir_publish-0.0.1.dist-info/METADATA,sha256=UqNoQHnNloQzYoKjVHdwM17BwL5kOqJ6cquYMesJHqc,4061
+userdir_publish-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+userdir_publish-0.0.1.dist-info/entry_points.txt,sha256=ggoLf8AxMWOUrl9k_BYsCV-OWKVAjawo65rUCof7H0M,60
+userdir_publish-0.0.1.dist-info/top_level.txt,sha256=0A-W2yAoOg8WfmCsosc840lnvwTntsI8Jt3JoF02fEY,16
+userdir_publish-0.0.1.dist-info/RECORD,,

userdir_publish-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

userdir_publish-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+userdir-publish = userdir_publish.cli:app

userdir_publish-0.0.1.dist-info/licenses/LICENSE

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

userdir_publish-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+userdir_publish