ldap-cli 0.2.0__py3-none-any.whl

ldapc/formatter.py

@@ -0,0 +1,282 @@
+"""Formatter module for ldapc.
+
+Provides LDAP search filter construction and output formatting functions
+for user and group entries. Supports aligned key-value text, JSON, and
+YAML output formats.
+"""
+
+from __future__ import annotations
+
+import json
+
+import yaml
+
+from ldapc.ldap_client import LdapEntry
+
+
+def build_user_filter(search_term: str) -> str:
+    """Construct an LDAP filter for user search (cn and uid).
+
+    Builds an OR filter that matches the search term as a substring
+    against both the common name (cn) and user ID (uid) attributes.
+
+    Args:
+        search_term: The term to search for in cn and uid fields.
+
+    Returns:
+        An LDAP filter string matching cn or uid.
+
+    Example:
+        >>> build_user_filter("john")
+        '(|(cn=*john*)(uid=*john*))'
+    """
+    return f"(|(cn=*{search_term}*)(uid=*{search_term}*))"
+
+
+def build_group_filter(search_term: str) -> str:
+    """Construct an LDAP filter for group search (cn).
+
+    Builds a filter that matches the search term as a substring
+    against the common name (cn) attribute.
+
+    Args:
+        search_term: The term to search for in the cn field.
+
+    Returns:
+        An LDAP filter string matching cn.
+
+    Example:
+        >>> build_group_filter("admin")
+        '(cn=*admin*)'
+    """
+    return f"(cn=*{search_term}*)"
+
+
+def format_user_entries(entries: list[LdapEntry]) -> str:
+    """Format user entries as aligned key-value text.
+
+    Displays each user entry's distinguished name, common name, email,
+    and group memberships. Multiple entries are separated by a delimiter
+    line. Keys are padded to a consistent width for alignment.
+
+    Args:
+        entries: List of LdapEntry objects representing user entries.
+
+    Returns:
+        A formatted string with aligned key-value pairs.
+    """
+    if not entries:
+        return ""
+
+    blocks: list[str] = []
+    for entry in entries:
+        lines = _format_user_block(entry)
+        blocks.append("\n".join(lines))
+
+    return "\n---\n".join(blocks)
+
+
+def format_group_entries(entries: list[LdapEntry]) -> str:
+    """Format group entries as aligned key-value text.
+
+    Displays each group entry's distinguished name, common name,
+    description, and member list. Multiple entries are separated by a
+    delimiter line. Keys are padded to a consistent width for alignment.
+
+    Args:
+        entries: List of LdapEntry objects representing group entries.
+
+    Returns:
+        A formatted string with aligned key-value pairs.
+    """
+    if not entries:
+        return ""
+
+    blocks: list[str] = []
+    for entry in entries:
+        lines = _format_group_block(entry)
+        blocks.append("\n".join(lines))
+
+    return "\n---\n".join(blocks)
+
+
+def format_entries_json(entries: list[LdapEntry]) -> str:
+    """Format entries as a JSON string.
+
+    Serializes a list of LdapEntry objects into a JSON array where each
+    element has "dn" and "attributes" keys.
+
+    Args:
+        entries: List of LdapEntry objects to serialize.
+
+    Returns:
+        A valid JSON string representing the entries.
+    """
+    data = [
+        {"dn": entry.dn, "attributes": entry.attributes}
+        for entry in entries
+    ]
+    return json.dumps(data, indent=2)
+
+
+def _format_user_block(entry: LdapEntry) -> list[str]:
+    """Format a single user entry as aligned key-value lines.
+
+    Args:
+        entry: An LdapEntry representing a user.
+
+    Returns:
+        A list of formatted lines.
+    """
+    cn = _get_first_attr(entry, "cn")
+    mail = _get_first_attr(entry, "mail")
+    groups = entry.attributes.get("memberOf", [])
+
+    key_width = 10  # Enough for "memberOf" + padding
+
+    lines = [
+        f"{'DN':<{key_width}}: {entry.dn}",
+        f"{'CN':<{key_width}}: {cn}",
+        f"{'Email':<{key_width}}: {mail}",
+    ]
+
+    if groups:
+        lines.append(f"{'Groups':<{key_width}}: {groups[0]}")
+        for group in groups[1:]:
+            lines.append(f"{'':<{key_width}}  {group}")
+    else:
+        lines.append(f"{'Groups':<{key_width}}: ")
+
+    return lines
+
+
+def _format_group_block(entry: LdapEntry) -> list[str]:
+    """Format a single group entry as aligned key-value lines.
+
+    Args:
+        entry: An LdapEntry representing a group.
+
+    Returns:
+        A list of formatted lines.
+    """
+    cn = _get_first_attr(entry, "cn")
+    description = _get_first_attr(entry, "description")
+    members = entry.attributes.get("member", [])
+
+    key_width = 12  # Enough for "Description" + padding
+
+    lines = [
+        f"{'DN':<{key_width}}: {entry.dn}",
+        f"{'CN':<{key_width}}: {cn}",
+        f"{'Description':<{key_width}}: {description}",
+    ]
+
+    if members:
+        lines.append(f"{'Members':<{key_width}}: {members[0]}")
+        for member in members[1:]:
+            lines.append(f"{'':<{key_width}}  {member}")
+    else:
+        lines.append(f"{'Members':<{key_width}}: ")
+
+    return lines
+
+
+def _get_first_attr(entry: LdapEntry, attr_name: str) -> str:
+    """Get the first value of an attribute, or empty string if missing.
+
+    Args:
+        entry: The LdapEntry to read from.
+        attr_name: The attribute name to look up.
+
+    Returns:
+        The first value of the attribute, or an empty string.
+    """
+    values = entry.attributes.get(attr_name, [])
+    return values[0] if values else ""
+
+
+def _extract_cn(dn: str) -> str:
+    """Extract the cn value from a DN string.
+
+    Args:
+        dn: A distinguished name like 'cn=admins,ou=groups,dc=example,dc=com'.
+
+    Returns:
+        The cn value (e.g. 'admins'), or the full DN if no cn= found.
+    """
+    for part in dn.split(","):
+        part = part.strip()
+        if part.lower().startswith("cn="):
+            return part[3:]
+    return dn
+
+
+def format_user_entries_yaml(entries: list[LdapEntry]) -> str:
+    """Format user entries as YAML.
+
+    Each entry becomes a YAML document with cn, email, and groups
+    (groups shown as just their cn component).
+
+    Args:
+        entries: List of LdapEntry objects representing user entries.
+
+    Returns:
+        A YAML-formatted string.
+    """
+    if not entries:
+        return ""
+
+    docs: list[str] = []
+    for entry in entries:
+        cn = _get_first_attr(entry, "cn")
+        mail = _get_first_attr(entry, "mail")
+        groups = entry.attributes.get("memberOf", [])
+
+        data: dict = {"cn": cn}
+        if mail:
+            data["email"] = mail
+        if groups:
+            data["groups"] = [_extract_cn(g) for g in groups]
+        else:
+            data["groups"] = []
+
+        docs.append(yaml.dump(data, default_flow_style=False, sort_keys=False).rstrip())
+
+    return "---\n" + "\n---\n".join(docs)
+
+
+def format_group_entries_yaml(entries: list[LdapEntry]) -> str:
+    """Format group entries as YAML.
+
+    Each entry becomes a YAML document with cn, description, and members
+    (members shown as just their cn or uid component).
+
+    Args:
+        entries: List of LdapEntry objects representing group entries.
+
+    Returns:
+        A YAML-formatted string.
+    """
+    if not entries:
+        return ""
+
+    docs: list[str] = []
+    for entry in entries:
+        cn = _get_first_attr(entry, "cn")
+        description = _get_first_attr(entry, "description")
+        members = entry.attributes.get("member", [])
+        member_uids = entry.attributes.get("memberUid", [])
+
+        data: dict = {"cn": cn}
+        if description:
+            data["description"] = description
+        if members:
+            data["members"] = [_extract_cn(m) for m in members]
+        elif member_uids:
+            data["members"] = member_uids
+        else:
+            data["members"] = []
+
+        docs.append(yaml.dump(data, default_flow_style=False, sort_keys=False).rstrip())
+
+    return "---\n" + "\n---\n".join(docs)