slack-objects 0.2.1__tar.gz → 0.3.0__tar.gz

{slack_objects-0.2.1 → slack_objects-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-objects
-Version: 0.2.1
+Version: 0.3.0
 Summary: Opinionated, testable Python wrappers for Slack’s Web, Admin, and SCIM APIs, organized by object domain (users, conversations, messages, files, workspaces, and IdP groups). Designed for automation and administration workflows.
 Author-email: "Marcos E. Mercado" <marcos_elias@hotmail.com>
 Keywords: slack,objects,classes,slack objects,utilities,slack utilities,slack object types,slack types,types

{slack_objects-0.2.1 → slack_objects-0.3.0}/src/slack_objects/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__commit_id__ = commit_id = 'g19585aaad'
+__commit_id__ = commit_id = 'g88ac46367'

{slack_objects-0.2.1 → slack_objects-0.3.0}/src/slack_objects/idp_groups.py

@@ -12,6 +12,7 @@ Manage Identity Provider (IdP) groups synced into Slack via SCIM.
 This module implements the following functionality:
 
 - list groups (paginated)
+- get a single group's full SCIM record (name, members, metadata)
 - get members of a given group
 - check whether a user is a member of a group
 
@@ -20,6 +21,11 @@ Design decisions
 - SCIM REST calls are centralized in ScimMixin._scim_request(); all public methods call endpoint wrappers.
 - Uses an injectable `requests.Session` (`scim_session`) so tests can pass a fake session.
 - Keeps legacy output shapes: lists of dicts for groups and members.
+- ``get_group()`` is the single read path for GET Groups/{id}; ``get_members()``,
+  ``is_member()`` and the ``display_name``/``members`` properties all compose on it
+  so the endpoint is only ever called from one place.
+- Attributes are loaded lazily (like ``Users``): binding a group_id does no network I/O,
+  the fetch happens on first property access or on ``refresh()``.
 - This module is SCIM-only. For Slack-native usergroups, see ``usergroups.py``.
 """
 
@@ -42,9 +48,18 @@ class IDP_groups(ScimMixin, SlackObjectBase):
         idp = slack.idp_groups()          # unbound
         bound = slack.idp_groups("S123")  # bound to a group_id
 
+    Binding a group_id performs no API call. `attributes` are loaded lazily via
+    `_require_attributes()` on first property access, so a single GET Groups/{id}
+    serves both the name and the members:
+
+        group = slack.idp_groups("S123")
+        name = group.display_name   # triggers the fetch
+        members = group.members     # served from the same cached response
+
     The SCIM session can be replaced for unit tests by passing scim_session argument.
     """
     group_id: Optional[str] = None
+    attributes: Dict[str, Any] = field(default_factory=dict)
     scim_session: requests.Session = field(default_factory=requests.Session, repr=False)
 
     # ---------- factory ----------
@@ -68,6 +83,41 @@ class IDP_groups(ScimMixin, SlackObjectBase):
             raise ValueError("group_id is required (passed or bound)")
         return gid
 
+    # ---------- lazily loaded attributes ----------
+
+    def refresh(self, group_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Refresh cached attributes for group_id (or self.group_id) using GET Groups/{id}.
+
+        Layered like ``Users.refresh()``: it calls the public ``get_group()``, which
+        calls the endpoint wrapper.
+        """
+        if group_id:
+            self.group_id = group_id
+        if not self.group_id:
+            raise ValueError("refresh() requires group_id (passed or already set)")
+
+        self.attributes = self.get_group(self.group_id)
+        return self.attributes
+
+    def _require_attributes(self) -> Dict[str, Any]:
+        """Ensure attributes are loaded (via refresh) before using helpers that read group fields."""
+        if self.attributes:
+            return self.attributes
+        if self.group_id:
+            return self.refresh()
+        raise ValueError("Group attributes not loaded and no group_id set (call refresh() or bind a group_id).")
+
+    @property
+    def display_name(self) -> str:
+        """The group's SCIM ``displayName`` (loaded lazily)."""
+        return self._require_attributes().get("displayName", "")
+
+    @property
+    def members(self) -> List[Dict[str, str]]:
+        """The group's members as ``{'value': <user id>, 'display': <name>}`` dicts (loaded lazily)."""
+        return self._require_attributes().get("members", []) or []
+
     # ---------- endpoint wrappers (only these call _scim_request) ----------
 
     def _scim_groups_list(self, *, count: int = 1000, start_index: Optional[int] = None) -> ScimResponse:
@@ -80,10 +130,21 @@ class IDP_groups(ScimMixin, SlackObjectBase):
             params["startIndex"] = start_index
         return self._scim_request(path="Groups", method="GET", params=params)   # https://docs.slack.dev/reference/scim-api/#get-groups
 
-    def _scim_group_get(self, group_id: str) -> ScimResponse:
-        """Wrapper for GET Groups/{id}"""
+    def _scim_group_get(self, group_id: str, *, count: Optional[int] = None, start_index: Optional[int] = None) -> ScimResponse:
+        """
+        Wrapper for GET Groups/{id}.
+
+        count/start_index page over the group's *members* sub-list, which matters for
+        groups larger than the server-side page size.
+        """
         validate_scim_id(group_id, "group_id")
-        return self._scim_request(path=f"Groups/{group_id}", method="GET")      # https://docs.slack.dev/reference/scim-api/#get-groups-id
+        params: Dict[str, Any] = {}
+        if count is not None:
+            params["count"] = count
+        if start_index is not None:
+            params["startIndex"] = start_index
+        # Pass params only when set, so the default call is byte-for-byte the legacy request.
+        return self._scim_request(path=f"Groups/{group_id}", method="GET", params=params or None)      # https://docs.slack.dev/reference/scim-api/#get-groups-id
 
     # ---------- public helpers ----------
 
@@ -130,16 +191,60 @@ class IDP_groups(ScimMixin, SlackObjectBase):
 
         return groups_out
 
+    def get_group(self, group_id: Optional[str] = None, *, fetch_count: int = 1000) -> Dict[str, Any]:
+        """
+        Return the full SCIM record for a single group (GET Groups/{id}).
+
+        One call yields both ``displayName`` and ``members``, so callers that need
+        the name do not have to pay for a second request. The complete payload is
+        returned (``id``, ``displayName``, ``members``, ``meta``, ``schemas``, ...) so
+        new SCIM fields are reachable without adding a method here.
+
+        When the response reports a ``totalResults`` larger than the members returned,
+        the remaining member pages are fetched and merged, so large groups are not
+        silently truncated.
+
+        Raises:
+            requests.HTTPError on non-2xx responses.
+        """
+        gid = self._resolve_group_id(group_id)
+
+        # First request sends no pagination params, so it is identical to the legacy call.
+        # Copy so callers mutating the result cannot corrupt our cached attributes.
+        group = dict(self._scim_group_get(gid).data)
+        members: List[Dict[str, str]] = list(group.get("members") or [])
+
+        # totalResults is only present when the server actually paged the members;
+        # when it is absent the single response is complete and we skip the loop.
+        total_results = group.get("totalResults")
+        if total_results is not None:
+            while len(members) < int(total_results):
+                # SCIM startIndex is 1-based, and the server chooses the first page size,
+                # so derive the cursor from what we already have rather than from fetch_count.
+                start_index = len(members) + 1
+                page_members = self._scim_group_get(gid, count=fetch_count, start_index=start_index).data.get("members") or []
+                # An empty page means the server has nothing more; stop rather than loop forever.
+                if not page_members:
+                    break
+                members.extend(page_members)
+
+        group["members"] = members
+        return group
+
     def get_members(self, group_id: Optional[str] = None) -> List[Dict[str, str]]:
         """
         Return group members via SCIM (GET Groups/{id}) as a list of dicts `{'value': <user_id>, 'display': <name>}`.
 
+        Composes on ``get_group()``; the cached attributes are reused when they already
+        describe the requested group, so property access and this method share one call.
+
         This module is SCIM-only. For Slack-native usergroups, see
         ``Usergroups.get_members()`` in ``usergroups.py``.
         """
         gid = self._resolve_group_id(group_id)
-        scim_resp = self._scim_group_get(gid)
-        return scim_resp.data.get("members", [])
+        if self.attributes and self.attributes.get("id") == gid:
+            return self.attributes.get("members", []) or []
+        return self.get_group(gid).get("members", []) or []
 
     def is_member(self, user_id: str, group_id: Optional[str] = None) -> bool:
         """
@@ -147,6 +252,9 @@ class IDP_groups(ScimMixin, SlackObjectBase):
 
         Higher-level convenience that composes on ``get_members()``.
         Preserves legacy semantics (scans the members list).
+
+        Each call fetches the group unless its attributes are already cached, so when
+        testing many users bind the group once (or hoist ``get_members()`` out of the loop).
         """
         members = self.get_members(group_id=group_id)
         for member in members:

{slack_objects-0.2.1 → slack_objects-0.3.0}/src/slack_objects.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-objects
-Version: 0.2.1
+Version: 0.3.0
 Summary: Opinionated, testable Python wrappers for Slack’s Web, Admin, and SCIM APIs, organized by object domain (users, conversations, messages, files, workspaces, and IdP groups). Designed for automation and administration workflows.
 Author-email: "Marcos E. Mercado" <marcos_elias@hotmail.com>
 Keywords: slack,objects,classes,slack objects,utilities,slack utilities,slack object types,slack types,types

slack_objects-0.3.0/src/slack_objects.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.3.0",
+  "distance": 0,
+  "node": "g88ac46367071865a9bb07d9ae48e7cc6116f5b72",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-06"
+}

{slack_objects-0.2.1 → slack_objects-0.3.0}/tests/UnitTests/idp_groups_unit_test.py

@@ -225,6 +225,134 @@ def test_get_members_and_is_member_with_bound_group():
     assert bound.is_member("U999") is False
 
 
+def test_get_group_returns_full_record_in_one_call():
+    """
+    Verifies:
+    - get_group() returns the complete SCIM payload (not just members)
+    - a single GET Groups/{id} serves both displayName and members
+    """
+    from slack_objects.idp_groups import IDP_groups
+
+    cfg = DummyConfig()
+    base = _scim_base(cfg, "v1")
+
+    group_payload = {
+        "id": "S123",
+        "displayName": "Admins",
+        "meta": {"created": "2024-01-01T00:00:00Z"},
+        "members": [{"value": "U111", "display": "Alice"}],
+    }
+
+    sess = FakeScimSession({("GET", f"{base}Groups/S123"): (200, group_payload)})
+
+    idp = IDP_groups(cfg=cfg, client=DummySlackClient(), logger=logging.getLogger("test"), api=DummyApiCaller(), scim_session=sess)
+    idp.rate_policy = RateLimitPolicy(method_overrides={}, prefix_rules={}, default=0.0)
+
+    group = idp.get_group("S123")
+
+    assert group["displayName"] == "Admins"
+    assert group["members"] == group_payload["members"]
+    # Unmapped fields stay reachable, which is why the full payload is returned.
+    assert group["meta"]["created"] == "2024-01-01T00:00:00Z"
+    assert len(sess.calls) == 1
+
+
+def test_bound_properties_load_lazily_and_share_one_call():
+    """
+    Verifies:
+    - binding a group_id performs no API call
+    - display_name triggers the fetch, and members reuses the cached response
+    """
+    from slack_objects.idp_groups import IDP_groups
+
+    cfg = DummyConfig()
+    base = _scim_base(cfg, "v1")
+
+    group_payload = {
+        "id": "S123",
+        "displayName": "Admins",
+        "members": [{"value": "U111", "display": "Alice"}],
+    }
+
+    sess = FakeScimSession({("GET", f"{base}Groups/S123"): (200, group_payload)})
+
+    group = IDP_groups(cfg=cfg, client=DummySlackClient(), logger=logging.getLogger("test"), api=DummyApiCaller(), scim_session=sess, group_id="S123")
+    group.rate_policy = RateLimitPolicy(method_overrides={}, prefix_rules={}, default=0.0)
+
+    # Construction must not perform network I/O.
+    assert sess.calls == []
+
+    assert group.display_name == "Admins"
+    assert group.members == group_payload["members"]
+    # get_members() must reuse the cache rather than issue a second request.
+    assert group.get_members() == group_payload["members"]
+    assert len(sess.calls) == 1
+
+
+def test_properties_require_a_bound_group_id():
+    """An unbound instance cannot lazily load, and must say so clearly."""
+    from slack_objects.idp_groups import IDP_groups
+
+    cfg = DummyConfig()
+    sess = FakeScimSession({})
+
+    idp = IDP_groups(cfg=cfg, client=DummySlackClient(), logger=logging.getLogger("test"), api=DummyApiCaller(), scim_session=sess)
+    idp.rate_policy = RateLimitPolicy(method_overrides={}, prefix_rules={}, default=0.0)
+
+    try:
+        idp.display_name
+    except ValueError:
+        pass
+    else:
+        raise AssertionError("display_name should raise ValueError when no group_id is bound")
+
+    assert sess.calls == []
+
+
+def test_get_group_merges_paginated_members():
+    """
+    Verifies:
+    - when totalResults exceeds the members returned, remaining pages are fetched
+    - members from all pages are merged, so large groups are not truncated
+    """
+    from slack_objects.idp_groups import IDP_groups
+
+    cfg = DummyConfig()
+
+    page1 = {
+        "id": "S123",
+        "displayName": "Admins",
+        "totalResults": 3,
+        "members": [{"value": "U111", "display": "Alice"}, {"value": "U222", "display": "Bob"}],
+    }
+    page2 = {
+        "id": "S123",
+        "displayName": "Admins",
+        "totalResults": 3,
+        "members": [{"value": "U333", "display": "Carol"}],
+    }
+
+    sess = FakeScimSession({})
+
+    calls = []
+
+    def request_side_effect(method: str, url: str, **kwargs):
+        calls.append(kwargs.get("params"))
+        return FakeResponse(200, page1 if len(calls) == 1 else page2)
+
+    sess.request = request_side_effect  # type: ignore[method-assign]
+
+    idp = IDP_groups(cfg=cfg, client=DummySlackClient(), logger=logging.getLogger("test"), api=DummyApiCaller(), scim_session=sess)
+    idp.rate_policy = RateLimitPolicy(method_overrides={}, prefix_rules={}, default=0.0)
+
+    group = idp.get_group("S123", fetch_count=2)
+
+    assert [m["value"] for m in group["members"]] == ["U111", "U222", "U333"]
+    # First call is the plain legacy request; the second resumes after what we already have.
+    assert calls[0] is None
+    assert calls[1]["startIndex"] == 3
+
+
 # -----------------------------
 # Optional "factory-style" demo
 # -----------------------------

slack_objects-0.2.1/src/slack_objects.egg-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.2.1",
-  "distance": 0,
-  "node": "g19585aaad5c9198c6559655f4d5f4931a5246563",
-  "dirty": false,
-  "branch": "HEAD",
-  "node_date": "2026-08-03"
-}