shortcuts

Shortcut wrappers for sanhe-confluence-sdk API with simplified parameters.

docpack_confluence.shortcuts.get_space_by_id(client: Confluence, space_id: int) → GetSpaceResponse[source]

Fetches a Confluence space by its ID.

Parameters:

  • client – Authenticated Confluence API client

  • space_id – ID of the Confluence space to fetch

docpack_confluence.shortcuts.get_space_by_key(client: Confluence, space_key: str) → GetSpacesResponseResult[source]

Fetches a Confluence space by its key.

Parameters:

  • client – Authenticated Confluence API client

  • space_key – Key of the Confluence space to fetch

docpack_confluence.shortcuts.get_pages_by_ids(client: Confluence, ids: list[int], body_format: str = 'atlas_doc_format') → list[GetPagesResponseResult][source]

Fetches multiple Confluence pages by their IDs in batches.

Parameters:

  • client – Authenticated Confluence API client

  • ids – List of Confluence page IDs to fetch

  • body_format – Format of the page body content

Returns:

List of page results strictly in the order of the provided IDs

docpack_confluence.shortcuts.get_pages_in_space(client: Confluence, space_id: int, limit: int = 9999) → Iterator[GetPagesInSpaceResponseResult][source]

Crawls and retrieves all pages from a Confluence space using pagination.

Parameters:

  • client – Authenticated Confluence API client

  • space_id – ID of the Confluence space to crawl

  • limit – Number of pages to fetch

Returns:

Iterator of page results from the space

docpack_confluence.shortcuts.get_descendants_of_page(client: Confluence, page_id: int, limit: int = 9999, depth: int = 5) → Iterator[GetPageDescendantsResponseResult][source]

Crawls and retrieves all descendant pages of a given Confluence page using pagination.

Parameters:

  • client – Authenticated Confluence API client

  • page_id – ID of the Confluence page whose descendants to fetch

  • limit – Number of descendant pages to fetch

docpack_confluence.shortcuts.get_descendants_of_folder(client: Confluence, folder_id: int, limit: int = 9999, depth: int = 5) → Iterator[GetFolderDescendantsResponseResult][source]

Crawls and retrieves all descendant entities of a given Confluence folder using pagination.

Parameters:

  • client – Authenticated Confluence API client

  • folder_id – ID of the Confluence folder whose descendants to fetch

  • limit – Maximum number of descendant entities to fetch

  • depth – Maximum depth to traverse (API limit is 5)

Returns:

Iterator of descendant results (pages and folders)

docpack_confluence.shortcuts.serialize_many(objects: list[HasRawData]) → bytes[source]

Serialize a list of objects with raw_data to gzip-compressed JSON bytes.

docpack_confluence.shortcuts.deserialize_many(b: bytes, klass: Type[T_RESPONSE]) → list[T_RESPONSE][source]

Deserialize gzip-compressed JSON bytes back to a list of objects.

docpack_confluence.shortcuts.get_pages_in_space_with_cache(client: Confluence, space_id: int, cache: CacheLike, cache_key: str | None = None, expire: int | None = 3600, force_refresh: bool = False, limit: int = 9999) → list[GetPagesInSpaceResponseResult][source]

Retrieves all pages from a Confluence space with disk caching.

Uses orjson for fast serialization of raw API response data.

Parameters:

  • client – Authenticated Confluence API client

  • space_id – ID of the Confluence space to crawl

  • cache – cache like instance for storing results

  • cache_key – Manual override for cache key (auto-generated if None)

  • expire – Cache expiration time in seconds (None for no expiration)

  • force_refresh – If True, bypass cache and fetch fresh data

  • limit – Maximum number of pages to fetch

Returns:

List of page results from the space

docpack_confluence.shortcuts.get_descendants_of_page_with_cache(client: Confluence, page_id: int, cache: CacheLike, cache_key: str | None = None, expire: int | None = 3600, force_refresh: bool = False, limit: int = 9999) → list[GetPageDescendantsResponseResult][source]

Retrieves all descendant pages of a Confluence page with disk caching.

Uses orjson for fast serialization of raw API response data.

Parameters:

  • client – Authenticated Confluence API client

  • page_id – ID of the Confluence page whose descendants to fetch

  • cache – cache like instance for storing results

  • cache_key – Manual override for cache key (auto-generated if None)

  • expire – Cache expiration time in seconds (None for no expiration)

  • force_refresh – If True, bypass cache and fetch fresh data

  • limit – Maximum number of descendant pages to fetch

Returns:

List of descendant page results

docpack_confluence.shortcuts.get_descendants_of_folder_with_cache(client: Confluence, folder_id: int, cache: CacheLike, cache_key: str | None = None, expire: int | None = 3600, force_refresh: bool = False, limit: int = 9999) → list[GetFolderDescendantsResponseResult][source]

Retrieves all descendant entities of a Confluence folder with disk caching.

Uses orjson for fast serialization of raw API response data.

Parameters:

  • client – Authenticated Confluence API client

  • folder_id – ID of the Confluence folder whose descendants to fetch

  • cache – cache like instance for storing results

  • cache_key – Manual override for cache key (auto-generated if None)

  • expire – Cache expiration time in seconds (None for no expiration)

  • force_refresh – If True, bypass cache and fetch fresh data

  • limit – Maximum number of descendant entities to fetch

Returns:

List of descendant results (pages and folders)

docpack_confluence.shortcuts.delete_pages_and_folders_in_space(client: Confluence, space_id: int, purge: bool = False, verbose: bool = True) → None[source]

Deletes all pages and folders in a Confluence space.

Uses crawl_descendants() to fetch the complete hierarchy (handles depth > 5), then deletes from deepest level first to avoid “parent folder can’t be deleted” errors.

Parameters:

  • client – Authenticated Confluence API client

  • space_id – ID of the Confluence space whose pages to delete

  • purge – If True, permanently delete (skip trash)

  • verbose – If True, print progress information

Algorithm:

Given hierarchy with max depth = 3:
    L1: [p1, f1]
    L2: [p2, f2, p3]
    L3: [p4, f3]

Delete order:
1. Delete all L3 entities: p4, f3
2. Delete all L2 entities: p2, f2, p3
3. Delete all L1 entities: p1, f1

This ensures children are always deleted before parents.
docpack_confluence.shortcuts.execute_with_retry(request: T_REQUEST, client: Confluence, max_retries: int = 3, initial_delay: float = 1.0, retry_on: set[int] | None = None, verbose: bool = True) → T_RESPONSE_TYPE[source]

Execute a request with retry logic for specific HTTP status codes.

Only retries when the response status code is in retry_on set. Other errors are raised immediately without retry.

Parameters:

  • request – Request object with a sync(client) method

  • client – Confluence API client

  • max_retries – Maximum number of retry attempts

  • initial_delay – Initial delay in seconds before first retry

  • retry_on – Set of HTTP status codes that should trigger a retry. Default is {404} (parent not found, common timing issue).

  • verbose – If True, print retry information

Returns:

Response from the successful request

Raises:

httpx.HTTPStatusError – If all retries fail or error is not retryable

Example:

request = CreatePageRequest(body_params=body_params)
response = execute_with_retry(request, client, retry_on={404, 503})
docpack_confluence.shortcuts.create_pages_and_folders(client: Confluence, space_id: int, hierarchy_specs: list[str], max_retries: int = 3, initial_delay: float = 1.0, retry_on: set[int] | None = None) → dict[str, str][source]

Create pages and folders in a Confluence space based on spec strings.

Spec format: - “p1” → create page with title “p1” under homepage - “f1” → create folder with title “f1” under homepage - “p2/p3” → create page with title “p3” under “p2” - “p2/f2” → create folder with title “f2” under “p2”

Naming convention: - Starts with “p” → page - Starts with “f” → folder

Parameters:

  • client – Authenticated Confluence API client

  • space_id – ID of the Confluence space

  • hierarchy_specs – List of spec strings (must be sorted by dependency order)

  • max_retries – Maximum number of retry attempts for failed requests

  • initial_delay – Initial delay in seconds before first retry

  • retry_on – Set of HTTP status codes that should trigger a retry. Default is {404} (parent not found).

Returns:

Dictionary mapping title to created entity ID