Skip to main content

passageway-connector-confluence

A passageway connector for Confluence Data Center (and Server): the current pages of the spaces you name, read through the REST API with GET requests only, using a personal access token. Written from the public REST documentation.

What it does

  • Each page is one item. Its id is the content id, its version changes with every page version and with its labels, and its link opens the page in Confluence.
  • Headings become sections: h1, h2 and h3 split a page into passages with their heading trail (Setup › Linux); lists, tables and code macros are kept readable; long sections are cut at about 350 tokens.
  • Labels become labels (space:OPS plus the page's own), ancestors become the path (nearest last, up to four), and every page weighs 1.0.
  • Macros: code and noformat macros keep their text; boxes, expands, sections, columns, excerpts and every other macro with a body keep what they hold; a status macro keeps its title; a table of contents, Jira issues, images, emoticons and other macros without a body are left out. Task lists become lists. Links keep their text, or the linked page's title. Blog posts and attachments are not indexed.
  • Edits appear within a minute: changed asks Confluence with CQL for the pages modified since the last poll (fourteen hours early, because CQL reads the time in the server's zone; unchanged versions cost nothing). Deletions, moves out of the spaces and labels that take a page out of scope are settled at the next reconcile. A space that lists no pages is reported as a warning, so a wrong key or a token without permission does not pass in silence.

Configure

Create a personal access token under your profile in Confluence (Data Center and Server 7.9 and later). The connector only ever sends GET requests.

[[connector]]
name = "wiki"
command = ["/path/to/python", "-m", "passageway_connector_confluence"]
env = { URL = "https://wiki.example.org", SPACES = "OPS|HR" }
secrets = { TOKEN = "env:CONFLUENCE_TOKEN" }
Setting Default Meaning
URL required The Confluence site, e.g. https://wiki.example.org (with its context path, if any)
SPACES required Space keys to index, separated by |
TOKEN required A personal access token, as a secret reference such as env:CONFLUENCE_TOKEN
INCLUDE_LABELS Only pages carrying one of these labels, separated by |
EXCLUDE_LABELS Pages carrying one of these labels are left out
MAX_PAGES 5000 Upper bound on the spaces together; more fails with a message instead of indexing a subset
TIMEOUT 30 Seconds per request
PAUSE_SECONDS 0 Pause between requests, for a busy server
VERIFY_TLS true false turns certificate checking off. A CA your operating system trusts already works without it (see Certificates), so prefer adding the CA there

Behaviour

  • Retries: 429 and 5xx answers and network errors are retried with a growing wait (1 s, doubling up to 60 s; a longer Retry-After is honoured up to 300 s) until a request has waited 15 minutes in total; the error then says how many attempts and how long it waited. Every wait of 10 s or more is logged as it starts (HTTP 429 … waiting 16 s (15 s of 900 s waited)), so a sync that waits does not look hung. A 401 says to check the token; any other error fails the call and nothing is stored.
  • A throttled or large space needs more than the core's default timeout = 300 for the whole list or fetch: waiting out one rate limit can take minutes. Raise timeout in its [[connector]] entry (3600 is a start), or set PAUSE_SECONDS so fewer requests are throttled in the first place.
  • Cloud: Atlassian Cloud authenticates with an e-mail address and an API token and serves the API under /wiki; it is not supported yet (ADR 0005).
  • Tested against a fake of the Data Center API in this repository, not against a live Confluence.

Test

uv run pytest connectors/confluence        # offline, against an in-test Confluence

Metadata

Release files for passageway-connector-confluence 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for passageway-connector-confluence 0.3.0
File Size Uploaded Provenance Actions
passageway_connector_confluence-0.3.0.tar.gz 15.9 kB Without provenance Details for passageway_connector_confluence-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for passageway-connector-confluence 0.3.0
File Interpreter ABI Platform Actions
passageway_connector_confluence-0.3.0-py3-none-any.whl Python 3 none any Details for passageway_connector_confluence-0.3.0-py3-none-any.whl

Total release size: 26.9 kB

Release files / passageway_connector_confluence-0.3.0.tar.gz

Download URL passageway_connector_confluence-0.3.0.tar.gz
Size 15.9 kB
Tags Source
SHA-256 checksum
How to use checksums
008ccb943d28cb8a47ca46752641c9ee4cfc6d655e321205799a6ceb86ed0803
BLAKE2b-256 checksum
How to use checksums
d35b794bc1990668da8513e830290565412c1e638b1068269f505c69167f1999
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / passageway_connector_confluence-0.3.0-py3-none-any.whl

Download URL passageway_connector_confluence-0.3.0-py3-none-any.whl
Size 11.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
46d5ac498b71788981fc2a1fd8d4016f0fa4060ebbddadfbdcaa60f77c366778
BLAKE2b-256 checksum
How to use checksums
6fa2366a5042bd1cdf7b33004676bed771b63fc3ca90c05409146071467082c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for passageway-connector-confluence 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page