Directory Search Controls

Design a small directory search helper that demonstrates scoped searches, alias handling, and paged retrieval against an LDAP-compatible directory.

Capabilities

Scope-aware search

• Searching with scope set to base returns only the base entry even if children exist. @test
• Searching with scope set to one-level returns only direct children of the base. @test
• Searching with scope set to subtree returns the base and all descendants. @test

Alias handling

• When alias resolution is disabled, alias entries are returned without following their targets. @test
• When alias resolution is enabled, results include the target entry data instead of the alias placeholder. @test

Paged results

• When result count exceeds the requested page size, multiple paged requests are made until no continuation marker remains, returning pages in order with each page respecting the requested size. @test

Implementation

@generates

API

from collections.abc import Callable
from typing import Any, Iterable


class DirectorySearchClient:
    def __init__(self, connection_factory: Callable[[], Any]):
        """Prepare a client that can obtain a fresh LDAP connection when needed."""

    def search(
        self,
        base_dn: str,
        filter_text: str,
        attributes: Iterable[str] | None,
        scope: str,
        deref_aliases: str,
    ) -> list[dict[str, Any]]:
        """Perform one search using the requested scope (base, one-level, or subtree) and alias handling (e.g., never vs always), returning entries as dictionaries."""

    def paged_search(
        self,
        base_dn: str,
        filter_text: str,
        attributes: Iterable[str] | None,
        page_size: int,
    ) -> list[list[dict[str, Any]]]:
        """Return ordered pages of entries, following paging markers until exhaustion."""

Dependencies { .dependencies }

ldap3 { .dependency }

Provides LDAP connectivity, scoped searches, alias dereference controls, and paging helpers.