ki_confluence

Toolkit for Atlassian Confluence using atlassian-python-api==4.0.7:

from atlassian import Confluence

confluence = Confluence(url=BASE_URL, token=API_TOKEN, cloud=True, verify_ssl=certs)

Structures: Space, Page, Table, Point (status lozenge).
Logs: structured JSON via loguru.

Install (PyPI)

pip install ki_confluence
# or
uv add ki_confluence

Requires Python ≥ 3.14.

cp .env.example .env   # CONFLUENCE_BASE_URL, CONFLUENCE_API_TOKEN, ...
ki_confluence --help

Development setup

uv sync
cp .env.example .env
uv run ruff check .
uv run ruff format .
uv run pytest

Build & publish to PyPI

# Build sdist + wheel into dist/
uv build --no-sources

# Dry-run upload
uv publish --dry-run

# Publish to TestPyPI first (recommended)
export UV_PUBLISH_TOKEN=pypi-...   # token from test.pypi.org
uv publish --index testpypi

# Publish to PyPI
export UV_PUBLISH_TOKEN=pypi-...   # token from pypi.org
uv publish

Create an API token at pypi.org/manage/account/token.

Structures

CLI (4.0.7)

# Space
uv run ki_confluence space get ENG

# Page (space KEY, not numeric id)
uv run ki_confluence page get 123456789
uv run ki_confluence page by-title --space ENG --title "Runbook"
uv run ki_confluence page create --space ENG --title "Runbook" --body '<p>hi</p>'
uv run ki_confluence page update 123456789 --body-file ./page.xml
uv run ki_confluence page set-slot 123456789 --name summary --content '<p>Updated</p>'

# Tables inside a page
uv run ki_confluence table list 123456789
uv run ki_confluence table set-cell 123456789 --row 1 --column 2 --value ok
uv run ki_confluence table set-by-header 123456789 --row-key api --header Status --value ok
uv run ki_confluence table update 123456789 --rows-json '[["api","platform","ok"]]'
uv run ki_confluence table add-row 123456789 --cells-json '["worker","data","up"]'
uv run ki_confluence table add-row 123456789 --row-json '{"Service":"cache","Owner":"platform","Status":"ok"}'

# Status points
uv run ki_confluence point list 123456789
uv run ki_confluence point set 123456789 --match-name PENDING --title HEALTHY --colour Green

# Inspect everything
uv run ki_confluence inspect 123456789

JSON logs go to stderr, e.g.:

{"timestamp":"...","level":"INFO","message":"get_page","extra":{"page_id":"123","component":"client"}}

Library

from ki_confluence import ConfluenceClient, Point, StatusColour, StorageDocument
from ki_confluence.logging import setup_logging

setup_logging("INFO")

with ConfluenceClient.from_env() as client:
    space = client.get_space("ENG")
    page = client.create_page(space_key=space.key, title="Demo", body="<p>x</p>")

    tables = client.list_tables(page.id)
    points = client.list_points(page.id)

    client.set_point(
        page.id,
        match_name="PENDING",
        title="OK",
        colour=StatusColour.GREEN,
    )
    client.set_table_cell_by_header(page.id, "api", "Status", "healthy")

See examples/basic_usage.py.

Notes

• 4.0.7 uses classic REST (/rest/api/content); create/update take space key.
• Auth: bearer token. CONFLUENCE_VERIFY_SSL = true / false / CA path.
• Bodies are Confluence storage XHTML (ac: / ri: macros).