docput 0.1.0__py3-none-any.whl

docput/__init__.py

@@ -0,0 +1,6 @@
+from pathlib import Path
+
+from .sphinx_ext import setup  # noqa: F401
+
+sphinx_templates = str(Path(__file__).parent / "sphinx_ext/_templates")
+sphinx_static = str(Path(__file__).parent / "sphinx_ext/_static")

docput/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

docput/cli/__init__.py

@@ -0,0 +1,5 @@
+from .main import main_group as main
+from .manifest import manifest_group as manifest
+from .version import version_group as version
+
+__all__ = [main, version, manifest]

docput/cli/main.py

@@ -0,0 +1,123 @@
+import shutil
+import sys
+from io import Writer
+from pathlib import Path
+from typing import Any, Callable
+
+import click
+
+from docput.path import URLPath
+from docput.remote import Remote, open_remote
+from docput.typing import Reader
+
+
+class RemoteParamType(click.ParamType[Remote]):
+    name = "URL"
+
+    def __init__(self, commit_on_close: bool = True):
+        self.commit_on_close = commit_on_close
+
+    def convert(
+        self, value: Any, param: click.Parameter | None, ctx: click.Context | None
+    ) -> Remote:
+        match value:
+            case Remote():
+                remote = value
+            case str(url):
+                remote = open_remote(url)
+            case _:
+                self.fail(f"Unknown value type {type(value)}")
+        if self.commit_on_close:
+            assert ctx is not None, "Cannot open remote without a context to bind it to"
+            ctx.with_resource(remote)
+        return remote
+
+
+def remote_option[FC: Callable[..., Any] | click.Command](
+    commit_on_close=True,
+    help="Remote to interact with",
+    **kwargs,
+) -> Callable[[FC], FC]:
+    return click.option(
+        "--remote",
+        "-r",
+        required=True,
+        type=RemoteParamType(commit_on_close),
+        envvar="DOCPUT_REMOTE",
+        show_envvar=True,
+        help=help,
+        **kwargs,
+    )
+
+
+@click.group(context_settings={"show_default": True, "max_content_width": 120})
+@click.version_option()
+def main_group(): ...
+
+
+@main_group.command(short_help="Download a file.")
+@remote_option(help="Remote to download from.")
+@click.argument("source", type=click.Path(path_type=URLPath))
+@click.argument("dest", type=click.File(mode="xb"))
+def download(remote: Remote, source: URLPath, dest: Writer[bytes]):
+    """Download SOURCE from the remote and write it to DEST"""
+    buff = remote.open_file(source)
+    shutil.copyfileobj(buff, dest)
+
+
+@main_group.command(short_help="Upload a file or directory.")  # type: ignore[attr-defined]
+@remote_option(help="Remote to upload to.")
+@click.option(
+    "--overwrite/--merge",
+    "-o/-m",
+    default=False,
+    is_flag=True,
+    show_default=True,
+    help="Merge or overwrite uploaded directories.",
+)
+@click.argument("source", type=click.Path(exists=True, allow_dash=True, path_type=Path))
+@click.argument("dest", type=click.Path(path_type=URLPath))
+def upload(
+    remote: Remote,
+    overwrite: bool,
+    source: Path | Reader[bytes],
+    dest: URLPath,
+):
+    """
+    Upload a file or directory SOURCE to the remote at DEST.
+
+    SOURCE is a path to a file or directory to upload. If SOURCE is `-`, its contents is read from standard input.
+
+    DEST is a path on the destination to write to.
+
+    If SOURCE is a file, its contents will be placed at DEST on the remote. Unlike tools like `cp` or `rsync`,
+    there is no special handling if DEST refers to a directory
+    """
+    if isinstance(source, Path) and str(source) == "-":
+        source = sys.stdin.buffer
+    remote.write(source, dest, overwrite)
+
+
+@main_group.command(short_help="Delete a file or directory.")
+@remote_option(help="Remote to delete from.")
+@click.argument("path", type=click.Path(path_type=URLPath))
+def rm(remote: Remote, path: URLPath):
+    """Delete the file or directory at PATH on the remote"""
+    remote.delete(path)
+
+
+@main_group.command(short_help="Create a symlink.")
+@remote_option(help="Remote to create a symlink on.")
+@click.argument("source", type=click.Path(path_type=URLPath))
+@click.argument("dest", type=click.Path(path_type=URLPath))
+def ln(remote: Remote, source: URLPath, dest: URLPath):
+    """Create a symlink on the remote at DEST pointing to SOURCE"""
+    remote.make_symlink(source, dest)
+
+
+@main_group.command(short_help="Create a directory.")
+@remote_option(help="Remote to create a directory on.")
+@click.argument("path", type=click.Path(path_type=URLPath))
+def mkdir(remote: Remote, path: URLPath):
+    """Create a directory on the remote at PATH. Any existing file or directory at PATH will be deleted"""
+    remote.make_dir(path)

docput/cli/manifest.py

@@ -0,0 +1,58 @@
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import click
+from click import ClickException
+
+from docput.config import get_config
+from .main import main_group, remote_option
+from ..manifest import VersionManifest
+
+
+@main_group.group(help="Edit the version manifest.")
+def manifest_group(): ...
+
+
+@manifest_group.command(short_help="Open the version manifest in a text editor")
+@remote_option()
+@click.option(
+    "--open",
+    "-O",
+    "editor",
+    is_flag=False,
+    flag_value=os.environ.get("EDITOR") or "nano",
+    help="Open the manifest file in a text editor and write it to the remote on exit.",
+)
+@click.option(
+    "--url",
+    "root_url",
+    metavar="URL",
+    help="""
+         Set the root URL to a new value. The root URL is the base for all hrefs in the version manifest. This must be absolute (either a path starting
+         with "/", or a full URL like "https://example.com/docs/"). If it is not set, it is assumed to be "/".
+         """,
+)
+def edit(remote, editor: str | None, root_url: str | None):
+    """Edit the version manifest."""
+    if editor is not None:
+        with TemporaryDirectory() as td:
+            tmp_path = Path(td) / get_config().get("manifest_url")
+            with open(tmp_path, "wb") as temp:
+                shutil.copyfileobj(remote.manifest.dump(), temp)
+            while True:
+                subprocess.run([editor, tmp_path], check=True)
+                try:
+                    with open(tmp_path, "rb") as temp:
+                        remote.manifest = VersionManifest(temp)
+                        return
+                except Exception as e:
+                    retry = click.confirm(f"Error parsing manifest file: {e}. Retry?")
+                    if not retry:
+                        raise ClickException(
+                            f"Aborting after error parsing manifest file: {e}"
+                        )
+    if root_url is not None:
+        remote.manifest.root_url = root_url

docput/cli/version.py

@@ -0,0 +1,183 @@
+import re
+from pathlib import Path
+from typing import Any, Callable
+
+import click
+from click import ClickException
+
+from .main import main_group, remote_option
+from ..config import get_config
+from ..manifest import VersionRecord
+from ..path import URLPath, reroot
+from ..remote import Remote
+
+
+def ref_option[FC: Callable[..., Any] | click.Command](**kwargs) -> Callable[[FC], FC]:  # type: ignore[name-defined]
+    return click.option(
+        "--ref",
+        "-R",
+        envvar=["DOCPUT_VERSION_REF", "FORGEJO_REF", "GITHUB_REF"],
+        show_envvar=True,
+        required=True,
+        **kwargs,
+    )
+
+
+@main_group.group(short_help="Create or edit versions.")
+def version_group(): ...
+
+
+@version_group.command(short_help="Push a documentation version to the remote.")
+@click.argument("source", type=click.Path(exists=True, file_okay=False, path_type=Path))
+@remote_option(help="Remote to push to.")
+@ref_option(help="Version reference to push to.")
+@click.option(
+    "--latest",
+    "-l",
+    is_flag=True,
+    default=False,
+    help="Mark this version as the latest release.",
+)
+@click.option(
+    "--visible/--hidden",
+    "-v/-h",
+    default=None,
+    help="Show this version in the version menu on the site.",
+)
+@click.option(
+    "--url",
+    "-u",
+    envvar=["DOCPUT_VERSION_URL"],
+    show_envvar=True,
+    help="""
+         Subdirectory on the site to write and link to. If not provided when pushing a new version, use the version ref with any text matching regex in the
+         config value `version.url_strip` removed. By default, this removes "refs/" from the start of the reference, so a version with the reference
+         `refs/tags/v1.0.0` would be published to `tags/v1.0.0`
+         """,
+)
+@click.option(
+    "--name",
+    "-n",
+    envvar=["DOCPUT_VERSION_NAME", "FORGEJO_REF_NAME", "GITHUB_REF_NAME"],
+    show_envvar=True,
+    help="The name to display for this version in the version menu.",
+)
+def push(
+    source: Path,
+    remote: Remote,
+    ref: str,
+    latest: bool,
+    visible: bool | None,
+    url: str | None,
+    name: str | None,
+):
+    """
+    Push a documentation version from SOURCE to the remote.
+    """
+    config = get_config()
+    manifest = remote.manifest
+    if (version := manifest.versions.get(ref)) is None:
+        # version does not exist in the manifest, so we need to make sure some values get filled in
+        if url is None:
+            url = re.sub(config.get("url_strip_regex"), "", ref)
+        version = VersionRecord(ref, {})
+        manifest.versions[ref] = version
+
+    # remove any old deployed versions. Old href may not equal the new href
+    if version.url is not None:
+        remote.delete(version.url)
+
+    # update the version properties
+    if name is not None:
+        version.name = name
+    if url is not None:
+        version.url = url
+    if visible is not None:
+        version.visible = visible
+
+    # root of the version we are deploying to
+    if version.url is None:
+        raise ClickException(f"Version {ref} has no href and none was provided")
+    version_url = URLPath(version.url)
+    assert not version_url.is_absolute(), "version URL must be a relative path"
+
+    # write local version and symlink in the manifest
+    remote.write(source, version_url, overwrite=True)
+    remote.make_symlink(
+        URLPath("/") / config.get("manifest_url"),
+        reroot(URLPath("/", version_url), config.get("manifest_url")),
+    )
+
+    # if this is the latest, make a symlink from /latest
+    if latest:
+        manifest.latest = version
+        latest_url = URLPath(config.get("latest_url"))
+        assert not latest_url.is_absolute(), "latest URL must be a relative path"
+        remote.make_symlink(version_url, latest_url)
+
+
+@version_group.command()
+@remote_option(help="Remote to delete the version from.")
+@ref_option(help="Version reference to delete.")
+@click.option(
+    "--keep",
+    is_flag=True,
+    default=False,
+    help="Keep the corresponding documentation, just delete the manifest record.",
+)
+def delete(remote: Remote, ref, keep):
+    """Delete a version from the remote."""
+    manifest = remote.manifest
+    if (latest := manifest.latest) is not None and latest.ref == ref:
+        manifest.latest = None
+
+    if (version := manifest.versions.pop(ref)) is None:
+        raise ClickException(f"Version {ref} does not exist in the manifest")
+
+    if not keep and version.url is not None:
+        remote.delete(version.url)
+
+
+@version_group.command()
+@remote_option(help="Remote to list versions on.", commit_on_close=False)
+def list_command(remote: Remote):
+    """List all versions in the manifest."""
+    for version in remote.manifest.versions.values():
+        print(version)
+
+
+@version_group.command()
+@remote_option()
+@ref_option()
+@click.option(
+    "--visible/--hidden",
+    "-v/-h",
+    help="Show this version in the version menu on the site.",
+)
+@click.option(
+    "--url",
+    "-u",
+    envvar=["DOCPUT_VERSION_URL"],
+    show_envvar=True,
+    help="URL on the site to write and link to. Must be a relative-path reference.",
+)
+@click.option(
+    "--name",
+    "-n",
+    envvar=["DOCPUT_VERSION_NAME"],
+    show_envvar=True,
+    help="The name to display for this version in the version menu.",
+)
+def edit(
+    remote: Remote, ref: str, visible: bool | None, url: str | None, name: str | None
+):
+    """Edit a version in the manifest."""
+    if (version := remote.manifest.versions.get(ref)) is None:
+        raise ClickException(f"Version {ref} does not exist in the manifest")
+
+    if visible is not None:
+        version.visible = visible
+    if url is not None:
+        version.url = url
+    if name is not None:
+        version.name = name

docput/config.py

@@ -0,0 +1,129 @@
+import os
+import tomllib
+from collections import UserDict
+from functools import cache
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+
+def project_root(start: str | PathLike[str] = os.curdir) -> Path:
+    """
+    Search for the project root, starting at the passed start path (default is the current directory).
+    Stops when it reaches a directory containing a ``pyproject.toml`` file, a ``.git`` directory, or a ``.hg`` directory, or the filesystem root.
+    This matches `the behavior of Black`_.
+
+    .. _the behavior of Black: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#where-black-looks-for-the-file
+    """
+    path = Path(start)
+    if not path.is_dir():
+        path = path.parent
+    for test_path in (path, *reversed(path.parents)):
+        for marker, is_dir in [
+            ("pyproject.toml", False),
+            (".git", True),
+            (".hg", True),
+        ]:
+            marker_path = test_path / marker
+            if marker_path.exists() and marker_path.is_dir() == is_dir:
+                return path
+    return path
+
+
+default_config = {
+    "manifest_url": "versions.json",
+    "latest_url": "latest",
+    "url_strip_regex": r"^refs/",
+}
+
+
+def _read_config(path: PathLike[str] | str | None) -> dict[str, Any]:
+    """
+    Read the tool config from ``pyproject.toml``. If pyproject.toml cannot be auto-resolved or does not contain the ``tool.docput`` table, an
+    empty dict is returned.
+    """
+    if path is None:
+        path = project_root() / "pyproject.toml"
+        if not path.exists():
+            # cannot locate pyproject.toml automatically
+            return {}
+    else:
+        path = Path(path)
+
+    tool_identifier = "docput"
+    with open(path, "rb") as fd:
+        toml = tomllib.load(fd)
+        if (tool_block := toml.get("tool")) is None:
+            return {}
+        if (settings_block := tool_block.get(tool_identifier)) is None:
+            return {}
+        assert isinstance(settings_block, dict)
+        return settings_block
+
+
+class _Sentinel: ...
+
+
+class DictConfig(UserDict):
+
+    def get(self, key: str, default=None):
+
+        def get_recursive(data, key, *rest):
+
+            try:
+                value = data[key]
+            except KeyError:
+                return default
+            match (value, *rest):
+                case [value]:
+                    return value
+                case [{**inner}, *rest]:
+                    return get_recursive(inner, *rest)
+                case [_, *rest]:
+                    raise KeyError(f"Unconsumed keys encountering non-dict: {rest}")
+
+            return default
+
+        return get_recursive(self.data, *key.split("."))
+
+
+class EnvConfig:
+    def __init__(self, prefix):
+        self.prefix = prefix.upper()
+
+    def get(self, key: str, default=None):
+        env_key = self.prefix + "_" + key.replace(".", "_").upper()
+        return os.environ.get(env_key, default)
+
+
+class CompoundConfig:
+
+    def __init__(self, configs):
+        self.configs = configs
+
+    def get(self, key: str, default=None):
+        _unset = _Sentinel()
+        for config in self.configs:
+            value = config.get(key, _unset)
+            if value is not _unset:
+                return value
+        return default
+
+    def __getitem__(self, key, /):
+        _unset = _Sentinel()
+        value = self.get(key, _unset)
+        if value is _unset:
+            raise KeyError(key)
+        return value
+
+
+@cache
+def get_config() -> CompoundConfig:
+    path = os.environ.get("DOCPUT_CONFIG_PATH")
+    return CompoundConfig(
+        [
+            EnvConfig("DOCPUT"),
+            DictConfig(_read_config(path)),
+            DictConfig(default_config),
+        ]
+    )

docput/manifest.py

@@ -0,0 +1,110 @@
+import json
+from io import BytesIO, TextIOWrapper
+from typing import Any
+
+from docput.typing import Reader
+
+
+class VersionManifest:
+    _data: dict[str, Any]
+    versions: dict[str, VersionRecord]
+
+    def __init__(self, fileobj: Reader[bytes] | None):
+        if fileobj is None:
+            self._data = {}
+        else:
+            self._data = json.load(fileobj)
+        version_data = self._data.get("versions", {})
+        assert isinstance(version_data, dict)
+        self.versions = {
+            ref: VersionRecord(ref, data) for ref, data in version_data.items()
+        }
+
+    @property
+    def root_url(self) -> str | None:
+        return self._data.get("root_url")
+
+    @root_url.setter
+    def root_url(self, value: str | None):
+        if value is None:
+            if "root_url" in self._data:
+                del self._data["root_url"]
+        else:
+            self._data["root_url"] = str(value)
+
+    @property
+    def latest(self) -> VersionRecord | None:
+        if (latest_ref := self._data.get("latest")) is not None:
+            return self.versions[latest_ref]
+        return None
+
+    @latest.setter
+    def latest(self, value: VersionRecord | None):
+        if value is None:
+            if "latest" in self._data:
+                del self._data["latest"]
+        else:
+            self._data["latest"] = value.ref
+
+    def as_json(self):
+        self._data["versions"] = {
+            ref: record.as_json() for ref, record in self.versions.items()
+        }
+        return self._data
+
+    def dump(self) -> BytesIO:
+        fileobj = TextIOWrapper(BytesIO(), "utf-8")
+        json.dump(self.as_json(), fileobj, indent=4)
+        fileobj.seek(0)
+        return fileobj.detach()
+
+
+class VersionRecord:
+    _ref: str
+    _data: dict[str, Any]
+
+    def __init__(self, ref: str, data: dict[str, Any]):
+        self._ref = ref
+        self._data = data
+
+    def __str__(self):
+        lines = [self.ref + ":"]
+        for key in ["name", "url", "visible"]:
+            if (value := self._data.get(key)) is not None:
+                lines.append(f"  {key}: {value}")
+
+        return "\n".join(lines)
+
+    def __repr__(self):
+        return self.as_json().__repr__()
+
+    @property
+    def ref(self):
+        return self._ref
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", self._ref)
+
+    @name.setter
+    def name(self, value: str):
+        self._data["name"] = value
+
+    @property
+    def url(self) -> str | None:
+        return self._data.get("url", None)
+
+    @url.setter
+    def url(self, value: str):
+        self._data["url"] = value
+
+    @property
+    def visible(self):
+        return self._data.get("visible", False)
+
+    @visible.setter
+    def visible(self, value: bool):
+        self._data["visible"] = value
+
+    def as_json(self):
+        return self._data