runspec-confluence-core 0.1.0__py3-none-any.whl

runspec_confluence_core/__init__.py

@@ -0,0 +1,67 @@
+"""runspec-confluence-core — Confluence helpers over atlassian-python-api.
+
+This package depends only on ``atlassian-python-api`` — it has **no dependency on
+runspec** and ships **no runspec.toml and no entry points**, so installing it
+exposes the helper functions for import without surfacing any runnables (it is
+invisible to ``runspec local`` / ``runspec serve`` discovery). ``runspec-confluence``
+depends on it and wraps each helper as a verb of the ``confluence`` runnable.
+
+Every operation takes an explicit :class:`ConfluenceConfig` first argument, so a
+private (e.g. Nexus-hosted) wrapper package can inject credentials in code, bake in
+a default ``space`` / ``env``, and build on top. Each function returns plain data
+and raises :class:`ConfluenceError` on failure. Cloud and Server/Data Center are
+both supported.
+"""
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import VALID_ENVS, ConfluenceConfig, config_from_env
+from runspec_confluence_core.content import (
+    add_comment,
+    add_label,
+    get_comments,
+    get_labels,
+    get_page_history,
+    get_page_restrictions,
+)
+from runspec_confluence_core.errors import ConfluenceError
+from runspec_confluence_core.pages import (
+    create_page,
+    delete_page,
+    get_page,
+    get_page_ancestors,
+    get_page_children,
+    get_space,
+    get_space_pages,
+    move_page,
+    update_page,
+)
+from runspec_confluence_core.search import search
+
+__all__ = [
+    # config / client
+    "ConfluenceConfig",
+    "ConfluenceError",
+    "config_from_env",
+    "build_client",
+    "translate_errors",
+    "VALID_ENVS",
+    # pages
+    "get_page",
+    "get_page_children",
+    "get_page_ancestors",
+    "create_page",
+    "update_page",
+    "delete_page",
+    "move_page",
+    "get_space_pages",
+    "get_space",
+    # search
+    "search",
+    # content
+    "get_page_history",
+    "get_labels",
+    "add_label",
+    "get_comments",
+    "add_comment",
+    "get_page_restrictions",
+]

runspec_confluence_core/client.py

@@ -0,0 +1,68 @@
+"""client.py — build an ``atlassian.Confluence`` client + shared op helpers.
+
+``build_client`` picks exactly one auth mode (Basic when username+api_token are
+set, else Bearer PAT). ``@translate_errors`` wraps each operation so the SDK's
+``requests`` exceptions surface as a :class:`ConfluenceError` carrying
+Confluence's own error message.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+import requests
+from atlassian import Confluence
+
+from runspec_confluence_core.config import ConfluenceConfig
+from runspec_confluence_core.errors import ConfluenceError
+
+_T = TypeVar("_T")
+
+
+def _auth_kwargs(config: ConfluenceConfig) -> dict[str, Any]:
+    base: dict[str, Any] = {"url": config.url, "cloud": config.cloud, "verify_ssl": config.verify_ssl}
+    if config.username and config.api_token:
+        base.update(username=config.username, password=config.api_token)
+    elif config.personal_token:
+        base.update(token=config.personal_token)
+    else:
+        raise ConfluenceError("ConfluenceConfig has no usable credentials (need personal_token or username+api_token)")
+    return base
+
+
+def build_client(config: ConfluenceConfig) -> Confluence:
+    """Construct an ``atlassian.Confluence`` client for ``config``."""
+    return Confluence(**_auth_kwargs(config))
+
+
+def _message(exc: requests.HTTPError) -> str:
+    """Extract a human-readable message from a Confluence error response."""
+    resp = getattr(exc, "response", None)
+    if resp is None:
+        return f"Confluence request failed: {exc}"
+    try:
+        body = resp.json()
+    except Exception:
+        return f"Confluence {resp.status_code}: {resp.text[:500]}"
+    if isinstance(body, dict):
+        message = body.get("message") or body.get("reason")
+        if message:
+            return f"Confluence {resp.status_code}: {message}"
+    return f"Confluence {resp.status_code}: {str(body)[:500]}"
+
+
+def translate_errors(fn: Callable[..., _T]) -> Callable[..., _T]:
+    """Decorator: turn the SDK's ``requests`` exceptions into ``ConfluenceError``."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> _T:
+        try:
+            return fn(*args, **kwargs)
+        except requests.HTTPError as exc:
+            raise ConfluenceError(_message(exc)) from exc
+        except requests.RequestException as exc:
+            raise ConfluenceError(f"Confluence request failed: {exc}") from exc
+
+    return wrapper

runspec_confluence_core/config.py

@@ -0,0 +1,108 @@
+"""config.py — connection + identity for a Confluence instance, from the environment.
+
+Mirrors ``runspec-jira-core``'s config: ``config_from_env`` reads the
+``CONFLUENCE_*`` family (with an optional ``CONFLUENCE_<ENV>_*`` prefix selected by
+``--env``). Every operation function takes an explicit ``ConfluenceConfig`` first
+argument, so a private (e.g. Nexus-hosted) wrapper can inject credentials in code
+and bake in a default ``space`` / ``env``.
+
+Cloud vs Server/Data Center is resolved once: an explicit ``CONFLUENCE_CLOUD`` wins,
+otherwise a ``.atlassian.net`` host is treated as Cloud and anything else as
+Server/DC.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from runspec_confluence_core.errors import ConfluenceError
+
+VALID_ENVS = ("dev", "uat", "prod")
+
+_FALSEY = ("0", "false", "no", "off")
+_TRUTHY = ("1", "true", "yes", "on")
+
+
+@dataclass
+class ConfluenceConfig:
+    """Connection + identity for a Confluence instance.
+
+    Provide EITHER ``personal_token`` (a Server/Data Center Personal Access Token,
+    sent as a Bearer token) OR ``username`` + ``api_token`` (Cloud email + API
+    token, or a Server/DC basic username + password). ``space`` is an optional
+    default a wrapper can bake in.
+    """
+
+    url: str
+    cloud: bool
+    username: str | None = None
+    api_token: str | None = None
+    personal_token: str | None = None
+    space: str | None = None
+    verify_ssl: bool = True
+    env: str | None = None
+
+
+def _env_first(names: list[str]) -> str | None:
+    """Return the first non-empty environment variable among ``names``."""
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
+def _resolve_cloud(url: str, override: str | None) -> bool:
+    """Decide Cloud vs Server/DC: explicit override wins, else infer from host."""
+    if override is not None:
+        return override.strip().lower() in _TRUTHY
+    return ".atlassian.net" in url.lower()
+
+
+def config_from_env(env: str | None = None) -> ConfluenceConfig:
+    """Build a :class:`ConfluenceConfig` from environment variables.
+
+    When ``env`` (or the ``CONFLUENCE_ENV`` variable) selects dev/uat/prod, the
+    environment-prefixed variables are read first (e.g. ``CONFLUENCE_UAT_URL``),
+    falling back to the unprefixed ``CONFLUENCE_*`` family. Raises
+    :class:`ConfluenceError` when the env label is invalid, the base URL is
+    missing, or no usable credentials are configured.
+    """
+    env = env or os.environ.get("CONFLUENCE_ENV")
+    if env is not None:
+        env = env.lower()
+        if env not in VALID_ENVS:
+            raise ConfluenceError(f"Invalid env {env!r} — expected one of {', '.join(VALID_ENVS)}")
+
+    def lookup(suffix: str) -> str | None:
+        names = []
+        if env:
+            names.append(f"CONFLUENCE_{env.upper()}_{suffix}")
+        names.append(f"CONFLUENCE_{suffix}")
+        return _env_first(names)
+
+    url = lookup("URL")
+    if not url:
+        hint = f"CONFLUENCE_{env.upper()}_URL" if env else "CONFLUENCE_URL"
+        raise ConfluenceError(f"No base URL configured — set {hint}")
+
+    username = lookup("USERNAME")
+    api_token = lookup("API_TOKEN")
+    personal_token = lookup("PERSONAL_TOKEN")
+    if not personal_token and not (username and api_token):
+        raise ConfluenceError("No credentials configured — set CONFLUENCE_PERSONAL_TOKEN (Server/DC PAT) or CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN (Cloud email + API token, or DC basic auth)")
+
+    verify = lookup("VERIFY_SSL")
+    verify_ssl = True if verify is None else verify.strip().lower() not in _FALSEY
+
+    return ConfluenceConfig(
+        url=url.rstrip("/"),
+        cloud=_resolve_cloud(url, lookup("CLOUD")),
+        username=username,
+        api_token=api_token,
+        personal_token=personal_token,
+        space=lookup("SPACE"),
+        verify_ssl=verify_ssl,
+        env=env,
+    )

runspec_confluence_core/content.py

@@ -0,0 +1,44 @@
+"""content.py — history, labels, comments, and restrictions for a page."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import ConfluenceConfig
+
+
+@translate_errors
+def get_page_history(config: ConfluenceConfig, page_id: str) -> Any:
+    """Return a page's content history (created/last-updated, versions)."""
+    return build_client(config).get_content_history(page_id)
+
+
+@translate_errors
+def get_labels(config: ConfluenceConfig, page_id: str) -> Any:
+    """List a page's labels."""
+    return build_client(config).get_page_labels(page_id)
+
+
+@translate_errors
+def add_label(config: ConfluenceConfig, page_id: str, label: str) -> Any:
+    """Add a label to a page."""
+    return build_client(config).set_page_label(page_id, label)
+
+
+@translate_errors
+def get_comments(config: ConfluenceConfig, page_id: str, *, limit: int = 25) -> Any:
+    """List a page's comments (rendered bodies)."""
+    return build_client(config).get_page_comments(page_id, expand="body.view", limit=limit)
+
+
+@translate_errors
+def add_comment(config: ConfluenceConfig, page_id: str, text: str) -> Any:
+    """Add a comment to a page."""
+    return build_client(config).add_comment(page_id, text)
+
+
+@translate_errors
+def get_page_restrictions(config: ConfluenceConfig, page_id: str) -> Any:
+    """Return the view/edit restrictions on a page."""
+    return build_client(config).get_all_restrictions_for_content(page_id)

runspec_confluence_core/errors.py

@@ -0,0 +1,13 @@
+"""errors.py — the exception type raised across runspec-confluence-core.
+
+Every operation function raises :class:`ConfluenceError` on configuration
+problems, invalid arguments, and non-2xx API responses (the underlying
+``atlassian-python-api`` raises ``requests`` exceptions, translated to
+``ConfluenceError`` at the operation boundary).
+"""
+
+from __future__ import annotations
+
+
+class ConfluenceError(Exception):
+    """Raised on config problems, invalid arguments, and Confluence API errors."""

runspec_confluence_core/pages.py

@@ -0,0 +1,114 @@
+"""pages.py — page read/create/update/delete/move + space listing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import ConfluenceConfig
+from runspec_confluence_core.errors import ConfluenceError
+
+
+@translate_errors
+def get_page(
+    config: ConfluenceConfig,
+    *,
+    page_id: str | None = None,
+    space: str | None = None,
+    title: str | None = None,
+    expand: str | None = None,
+) -> Any:
+    """Fetch a page by id, or by space + title. ``expand`` (e.g.
+    ``body.storage,version``) controls what is returned."""
+    client = build_client(config)
+    if page_id:
+        return client.get_page_by_id(page_id, expand=expand)
+    space = space or config.space
+    if space and title:
+        return client.get_page_by_title(space, title, expand=expand)
+    raise ConfluenceError("get-page needs --page-id, or --space (or CONFLUENCE_SPACE) and --title")
+
+
+@translate_errors
+def get_page_children(config: ConfluenceConfig, page_id: str) -> Any:
+    """List a page's immediate child pages."""
+    return build_client(config).get_child_pages(page_id)
+
+
+@translate_errors
+def get_page_ancestors(config: ConfluenceConfig, page_id: str) -> Any:
+    """List a page's ancestor pages (its breadcrumb, root first)."""
+    return build_client(config).get_page_ancestors(page_id)
+
+
+@translate_errors
+def create_page(
+    config: ConfluenceConfig,
+    space: str,
+    title: str,
+    body: str,
+    *,
+    parent_id: str | None = None,
+    representation: str = "storage",
+) -> Any:
+    """Create a page. ``body`` is in ``representation`` format (``storage`` XHTML by
+    default, or ``wiki`` / ``editor``)."""
+    return build_client(config).create_page(space, title, body, parent_id=parent_id, representation=representation)
+
+
+@translate_errors
+def update_page(
+    config: ConfluenceConfig,
+    page_id: str,
+    title: str,
+    *,
+    body: str | None = None,
+    parent_id: str | None = None,
+    representation: str = "storage",
+    version_comment: str | None = None,
+    minor_edit: bool = False,
+) -> Any:
+    """Update a page. ``title`` is required by the API even when only the body
+    changes (pass the page's current title)."""
+    return build_client(config).update_page(
+        page_id,
+        title,
+        body=body,
+        parent_id=parent_id,
+        representation=representation,
+        minor_edit=minor_edit,
+        version_comment=version_comment,
+    )
+
+
+@translate_errors
+def delete_page(config: ConfluenceConfig, page_id: str, *, recursive: bool = False) -> dict[str, Any]:
+    """Delete a page (and, with ``recursive``, its descendants)."""
+    build_client(config).remove_page(page_id, recursive=recursive)
+    return {"page_id": page_id, "deleted": True}
+
+
+@translate_errors
+def move_page(
+    config: ConfluenceConfig,
+    space: str,
+    page_id: str,
+    *,
+    target_id: str | None = None,
+    target_title: str | None = None,
+    position: str = "append",
+) -> Any:
+    """Move a page relative to a target (``append`` under it, or ``above``/``below``)."""
+    return build_client(config).move_page(space, page_id, target_id=target_id, target_title=target_title, position=position)
+
+
+@translate_errors
+def get_space_pages(config: ConfluenceConfig, space: str, *, start: int = 0, limit: int = 50) -> Any:
+    """List pages in a space (one page of results)."""
+    return build_client(config).get_all_pages_from_space(space, start=start, limit=limit)
+
+
+@translate_errors
+def get_space(config: ConfluenceConfig, space_key: str) -> Any:
+    """Fetch a space's metadata."""
+    return build_client(config).get_space(space_key)

runspec_confluence_core/search.py

@@ -0,0 +1,15 @@
+"""search.py — CQL content search."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runspec_confluence_core.client import build_client, translate_errors
+from runspec_confluence_core.config import ConfluenceConfig
+
+
+@translate_errors
+def search(config: ConfluenceConfig, cql: str, *, start: int = 0, limit: int = 25, expand: str | None = None) -> Any:
+    """Search content with CQL (Confluence Query Language), e.g.
+    ``type = page AND space = DOCS AND text ~ "onboarding"``. Returns one page."""
+    return build_client(config).cql(cql, start=start, limit=limit, expand=expand)

runspec_confluence_core-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: runspec-confluence-core
+Version: 0.1.0
+Summary: Pure-Python Confluence helpers (over atlassian-python-api) — the importable core behind runspec-confluence (no runspec dependency, no runnables)
+Requires-Python: >=3.10
+Requires-Dist: atlassian-python-api>=3.41
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_confluence_core-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+runspec_confluence_core/__init__.py,sha256=6AYUHa5uu8egbvEDnCIDLisaBfcyK3Q7W301xAo1Kvs,2007
+runspec_confluence_core/client.py,sha256=5pevGx2_5icDJSYybFK0t8da8h4RiitFitrS6MKBeKw,2480
+runspec_confluence_core/config.py,sha256=eSkolXkChGl_R2hTj0prDH7mpn6ynuzeSG992DswA-c,3922
+runspec_confluence_core/content.py,sha256=ySC2lW_fDtveRAaCsh-MAzcW-uJIIVrUo2e1EP5yqPs,1521
+runspec_confluence_core/errors.py,sha256=KmYNrBRV0ynA2IuCFk5pgYSXBZLDx4XwM0c87hRmnys,499
+runspec_confluence_core/pages.py,sha256=vlGWUjVB9r3ZBy9bsVc1gTfkTjt7gGln_RDz_bq2ZZI,3689
+runspec_confluence_core/search.py,sha256=JY351R3FMmbcIWcJ1sR1HbMGNNAQJopzczIleG2tahw,603
+runspec_confluence_core-0.1.0.dist-info/METADATA,sha256=KUue8lh2ZTOuY28GC4HHazDvAG97r68L0MiRixTaulk,433
+runspec_confluence_core-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+runspec_confluence_core-0.1.0.dist-info/RECORD,,

runspec_confluence_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any