selector

Confluence page selector with include/exclude filter rules.

This module implements the filter language defined in the documentation, supporting URL-based matching with wildcard syntax.

class docpack_confluence.selector.MatchMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Defines how a pattern matches against a page’s path.

• SELF: Match only the node itself (no wildcard)

• DESCENDANTS: Match all descendants, excluding the node itself (/*)

• RECURSIVE: Match the node and all its descendants (/**)

is_self() → bool

Check if the mode is SELF.

is_descendant() → bool

Check if the mode is DESCENDANTS.

is_recursive() → bool

Check if the mode is RECURSIVE.

class docpack_confluence.selector.Pattern(id: str, mode: MatchMode)

A matching pattern parsed from a Confluence URL.

Parameters:

• id – The page or folder ID extracted from the URL

• mode – The matching mode (SELF, DESCENDANTS, or RECURSIVE)

docpack_confluence.selector.parse_pattern(url: str) → Pattern

Parse a Confluence URL into a Pattern object.

Supports three formats: - {url} -> MatchMode.SELF (match only the node) - {url}/* -> MatchMode.DESCENDANTS (match all descendants) - {url}/** -> MatchMode.RECURSIVE (match node and all descendants)

Parameters:

url – Confluence page or folder URL, optionally with /* or /** suffix

Returns:

Parsed Pattern object

Raises:

ValueError – If the URL format is not recognized

docpack_confluence.selector.is_match(pattern: Pattern, id_path: list[str]) → bool

Check if a page’s ID path matches the given pattern.

Parameters:

• pattern – The pattern to match against

• id_path – The page’s full ID path from root to current node, e.g., [“p1”, “f1”, “p2”] means the page is at p1 -> f1 -> p2

Returns:

True if the path matches the pattern, False otherwise

Matching rules:

• SELF: The page’s ID (last element) must equal pattern.id

• DESCENDANTS: pattern.id must be an ancestor (not the page itself)

• RECURSIVE: pattern.id must be in the path (ancestor or self)

Examples:

>>> path = ["p1", "f1", "p2"]  # page p2 under f1 under p1
>>> is_match(Pattern("p2", MatchMode.SELF), path)
True   # p2 is the page itself
>>> is_match(Pattern("p1", MatchMode.SELF), path)
False  # p1 is not the page itself
>>> is_match(Pattern("p1", MatchMode.DESCENDANTS), path)
True   # p2 is a descendant of p1
>>> is_match(Pattern("p2", MatchMode.DESCENDANTS), path)
False  # p2 has no descendants here
>>> is_match(Pattern("p1", MatchMode.RECURSIVE), path)
True   # p2 is under p1
>>> is_match(Pattern("p2", MatchMode.RECURSIVE), path)
True   # p2 is itself

class docpack_confluence.selector.Selector(include: list[str] = <factory>, exclude: list[str] = <factory>)

Page selector with include/exclude filter rules.

Parameters:

• include – List of URL patterns to include. Empty list means include all.

• exclude – List of URL patterns to exclude. Empty list means exclude nothing.

Priority: exclude > include. If a page matches both, it is excluded.

Example:

selector = Selector(
    include=["https://example.atlassian.net/wiki/spaces/DEMO/pages/123/Title/**"],
    exclude=["https://example.atlassian.net/wiki/spaces/DEMO/pages/456/Other/*"],
)

# Check if a page should be included
if selector.should_include(page_id_path):
    # Process this page
    ...

should_include(id_path: list[str]) → bool

Determine if a page should be included based on filter rules.

Parameters:

id_path – The page’s full ID path from root to current node

Returns:

True if the page should be included, False otherwise

Logic:

1. If exclude patterns exist and page matches any -> excluded

2. If include patterns are empty -> included (include all)

3. If include patterns exist and page matches any -> included

4. Otherwise -> excluded

select(pages: Iterable[tuple[str, list[str]]]) → Iterator[tuple[str, list[str]]]

Filter pages based on include/exclude rules.

Parameters:

pages – Iterable of (page_id, id_path) tuples

Returns:

Iterator of pages that pass the filter