slack-objects 0.1.0__tar.gz → 0.1.2__tar.gz

slack_objects-0.1.2/.github/copilot-instructions.md

@@ -0,0 +1,8 @@
+# Copilot Instructions
+
+## Project Guidelines
+- Follow Unix philosophy: build small, composable functions where higher-level methods leverage lower-level primitives. Don't mix concerns (e.g., don't embed identifier resolution inside a SCIM CRUD method). Keep signatures consistent across sibling methods.
+- Prefer consistency with the `Users.is_active`/`is_active_scim` pattern when structuring related methods (separate explicit SCIM method from higher-level orchestration).
+
+## Testing Guidelines
+- Unit test files in `tests/UnitTests` must follow the naming convention `*_unit_test.py` (not `test_*` prefix). The following files should adhere to this convention: `users_unit_test.py`, `conversations_unit_test.py`, `messages_unit_test.py`, `files_unit_test.py`, `workspaces_unit_test.py`, `idp_groups_unit_test.py`, `config_unit_test.py`, and two others with the `_unit_test.py` suffix.

{slack_objects-0.1.0 → slack_objects-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-objects
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 A focused Python package for working with **Slack objects** commonly used in administration and automation workflows.
 
-`slack-objects` provides **opinionated, testable wrappers** around the Slack Web API, Admin API, and SCIM API—favoring object-based access over raw endpoint calls.
+`slack-objects` provides **opinionated, testable wrappers** around the Slack Web API, Admin API, SCIM API, and Discovery API—favoring object-based access over raw endpoint calls.
 
 ---
 
@@ -55,7 +55,7 @@ Instead, it focuses on higher-level object operations that typically require:
 - multiple API calls
 - pagination
 - rate limiting
-- Admin API or SCIM usage
+- Admin API, SCIM, or Discovery API usage
 - non-trivial orchestration logic
 
 ---
@@ -73,7 +73,7 @@ cfg = SlackObjectsConfig(
     bot_token="xoxb-...",
     user_token="xoxp-...",
     scim_token="xoxp-...",
-    # see SlackObjectsConfig for additional options (scim_base_url, http_timeout_seconds, etc.)
+    # see SlackObjectsConfig for additional options (team_id, scim_base_url, http_timeout_seconds, etc.)
 )
 
 slack = SlackObjectsClient(cfg)
@@ -139,6 +139,8 @@ The codebase is designed to be tested **without hitting Slack**.
 
 ## Installation
 
+Requires **Python 3.9+**.
+
 ```bash
 pip install slack-objects
 ```
@@ -154,7 +156,8 @@ cfg = SlackObjectsConfig(
     bot_token="xoxb-...",
     user_token="xoxp-...",
     scim_token="xoxp-...",
-    default_rate_tier=RateTier.TIER_3,  # fallback sleep between API calls when no specific tier matches
+    team_id="T0123ABC",                 # workspace ID; required for org-wide tokens calling workspace-scoped Web APIs
+    default_rate_tier=RateTier.TIER_2,  # fallback sleep between API calls when no specific tier matches (default)
 )
 ```
 
@@ -175,10 +178,23 @@ python -m tests.Smoke.run_all_smoke
 
 ---
 
+## Rate Limiting
+All Slack Web/Admin API calls go through `SlackApiCaller`, which:
+
+- Sleeps according to the resolved rate tier after every successful call
+- Automatically retries on HTTP **429** (rate-limited) responses up to **5 times**, respecting the `Retry-After` header
+
+Rate tiers are resolved in priority order:
+explicit per-call tier → method-specific override → prefix rule → `default_rate_tier` from config.
+
+---
+
 ## Notes
 
 - SCIM v2 is the default; v1 is supported where applicable
-- `PC_Utils` is an optional dependency (used for datetime handling in `set_guest_expiration_date`)
+- `PC_Utils` is a required dependency (used for datetime handling in `set_guest_expiration_date`)
 - This package is intended for automation and administration workflows
 - `resolve_user_id` accepts flexible identifiers (user ID, email, or @username) and verifies existence via Web API + SCIM fallback
 - `is_user_authorized` supports IdP-group-based authorization checks with configurable read/write access levels
+- SCIM user operations are available on `Users`: create, deactivate, reactivate, update attributes, update email, and convert to multi-channel guest
+- Discovery API is used for `Users.get_channels` and `Conversations.get_members` (requires appropriate token scopes)

{slack_objects-0.1.0 → slack_objects-0.1.2}/README.md

@@ -2,7 +2,7 @@
 
 A focused Python package for working with **Slack objects** commonly used in administration and automation workflows.
 
-`slack-objects` provides **opinionated, testable wrappers** around the Slack Web API, Admin API, and SCIM API—favoring object-based access over raw endpoint calls.
+`slack-objects` provides **opinionated, testable wrappers** around the Slack Web API, Admin API, SCIM API, and Discovery API—favoring object-based access over raw endpoint calls.
 
 ---
 
@@ -34,7 +34,7 @@ Instead, it focuses on higher-level object operations that typically require:
 - multiple API calls
 - pagination
 - rate limiting
-- Admin API or SCIM usage
+- Admin API, SCIM, or Discovery API usage
 - non-trivial orchestration logic
 
 ---
@@ -52,7 +52,7 @@ cfg = SlackObjectsConfig(
     bot_token="xoxb-...",
     user_token="xoxp-...",
     scim_token="xoxp-...",
-    # see SlackObjectsConfig for additional options (scim_base_url, http_timeout_seconds, etc.)
+    # see SlackObjectsConfig for additional options (team_id, scim_base_url, http_timeout_seconds, etc.)
 )
 
 slack = SlackObjectsClient(cfg)
@@ -118,6 +118,8 @@ The codebase is designed to be tested **without hitting Slack**.
 
 ## Installation
 
+Requires **Python 3.9+**.
+
 ```bash
 pip install slack-objects
 ```
@@ -133,7 +135,8 @@ cfg = SlackObjectsConfig(
     bot_token="xoxb-...",
     user_token="xoxp-...",
     scim_token="xoxp-...",
-    default_rate_tier=RateTier.TIER_3,  # fallback sleep between API calls when no specific tier matches
+    team_id="T0123ABC",                 # workspace ID; required for org-wide tokens calling workspace-scoped Web APIs
+    default_rate_tier=RateTier.TIER_2,  # fallback sleep between API calls when no specific tier matches (default)
 )
 ```
 
@@ -154,10 +157,23 @@ python -m tests.Smoke.run_all_smoke
 
 ---
 
+## Rate Limiting
+All Slack Web/Admin API calls go through `SlackApiCaller`, which:
+
+- Sleeps according to the resolved rate tier after every successful call
+- Automatically retries on HTTP **429** (rate-limited) responses up to **5 times**, respecting the `Retry-After` header
+
+Rate tiers are resolved in priority order:
+explicit per-call tier → method-specific override → prefix rule → `default_rate_tier` from config.
+
+---
+
 ## Notes
 
 - SCIM v2 is the default; v1 is supported where applicable
-- `PC_Utils` is an optional dependency (used for datetime handling in `set_guest_expiration_date`)
+- `PC_Utils` is a required dependency (used for datetime handling in `set_guest_expiration_date`)
 - This package is intended for automation and administration workflows
 - `resolve_user_id` accepts flexible identifiers (user ID, email, or @username) and verifies existence via Web API + SCIM fallback
 - `is_user_authorized` supports IdP-group-based authorization checks with configurable read/write access levels
+- SCIM user operations are available on `Users`: create, deactivate, reactivate, update attributes, update email, and convert to multi-channel guest
+- Discovery API is used for `Users.get_channels` and `Conversations.get_members` (requires appropriate token scopes)

slack_objects-0.1.2/src/slack_objects/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
+
+__commit_id__ = commit_id = 'ge0d1b7810'

{slack_objects-0.1.0 → slack_objects-0.1.2}/src/slack_objects/users.py

@@ -626,12 +626,20 @@ class Users(ScimMixin, SlackObjectBase):
     def scim_update_user_attribute(
         self,
         *,
-        user_id: str,
+        user_id: Optional[str] = None,
         attribute: str,
         new_value: Any,
     ) -> ScimResponse:
-        """SCIM PATCH Users/<id>"""
-        validate_scim_id(user_id, "user_id")
+        """SCIM PATCH Users/<id> for simple scalar attributes.
+
+        For email updates, use :meth:`scim_update_email` instead — it handles
+        the version-specific payload formatting needed to avoid multi-primary
+        conflicts.
+        """
+        uid = user_id or self.user_id
+        if not uid:
+            raise ValueError("scim_update_user_attribute requires user_id (passed or bound)")
+        validate_scim_id(uid, "user_id")
 
         scim_version = self.cfg.scim_version
         if scim_version == "v2":
@@ -644,7 +652,7 @@ class Users(ScimMixin, SlackObjectBase):
         else:
             raise NotImplementedError(f"Invalid SCIM version: {scim_version}")
 
-        return self._scim_request(path=f"Users/{user_id}", method="PATCH", payload=payload)
+        return self._scim_request(path=f"Users/{uid}", method="PATCH", payload=payload)
 
     def scim_update_email(
         self,

{slack_objects-0.1.0 → slack_objects-0.1.2}/src/slack_objects.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-objects
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -23,7 +23,7 @@ Dynamic: license-file
 
 A focused Python package for working with **Slack objects** commonly used in administration and automation workflows.
 
-`slack-objects` provides **opinionated, testable wrappers** around the Slack Web API, Admin API, and SCIM API—favoring object-based access over raw endpoint calls.
+`slack-objects` provides **opinionated, testable wrappers** around the Slack Web API, Admin API, SCIM API, and Discovery API—favoring object-based access over raw endpoint calls.
 
 ---
 
@@ -55,7 +55,7 @@ Instead, it focuses on higher-level object operations that typically require:
 - multiple API calls
 - pagination
 - rate limiting
-- Admin API or SCIM usage
+- Admin API, SCIM, or Discovery API usage
 - non-trivial orchestration logic
 
 ---
@@ -73,7 +73,7 @@ cfg = SlackObjectsConfig(
     bot_token="xoxb-...",
     user_token="xoxp-...",
     scim_token="xoxp-...",
-    # see SlackObjectsConfig for additional options (scim_base_url, http_timeout_seconds, etc.)
+    # see SlackObjectsConfig for additional options (team_id, scim_base_url, http_timeout_seconds, etc.)
 )
 
 slack = SlackObjectsClient(cfg)
@@ -139,6 +139,8 @@ The codebase is designed to be tested **without hitting Slack**.
 
 ## Installation
 
+Requires **Python 3.9+**.
+
 ```bash
 pip install slack-objects
 ```
@@ -154,7 +156,8 @@ cfg = SlackObjectsConfig(
     bot_token="xoxb-...",
     user_token="xoxp-...",
     scim_token="xoxp-...",
-    default_rate_tier=RateTier.TIER_3,  # fallback sleep between API calls when no specific tier matches
+    team_id="T0123ABC",                 # workspace ID; required for org-wide tokens calling workspace-scoped Web APIs
+    default_rate_tier=RateTier.TIER_2,  # fallback sleep between API calls when no specific tier matches (default)
 )
 ```
 
@@ -175,10 +178,23 @@ python -m tests.Smoke.run_all_smoke
 
 ---
 
+## Rate Limiting
+All Slack Web/Admin API calls go through `SlackApiCaller`, which:
+
+- Sleeps according to the resolved rate tier after every successful call
+- Automatically retries on HTTP **429** (rate-limited) responses up to **5 times**, respecting the `Retry-After` header
+
+Rate tiers are resolved in priority order:
+explicit per-call tier → method-specific override → prefix rule → `default_rate_tier` from config.
+
+---
+
 ## Notes
 
 - SCIM v2 is the default; v1 is supported where applicable
-- `PC_Utils` is an optional dependency (used for datetime handling in `set_guest_expiration_date`)
+- `PC_Utils` is a required dependency (used for datetime handling in `set_guest_expiration_date`)
 - This package is intended for automation and administration workflows
 - `resolve_user_id` accepts flexible identifiers (user ID, email, or @username) and verifies existence via Web API + SCIM fallback
 - `is_user_authorized` supports IdP-group-based authorization checks with configurable read/write access levels
+- SCIM user operations are available on `Users`: create, deactivate, reactivate, update attributes, update email, and convert to multi-channel guest
+- Discovery API is used for `Users.get_channels` and `Conversations.get_members` (requires appropriate token scopes)

{slack_objects-0.1.0 → slack_objects-0.1.2}/tests/SCIM/test_scim_users_update_attribute_live.py

@@ -190,6 +190,21 @@ class TestScimUpdateUserAttribute:
         )
         _pause()
 
+    # ----- bound user_id (no explicit user_id) -----
+
+    def test_update_attribute_bound_user(self, ctx, users):
+        """Update attribute using bound user_id (no explicit user_id arg)."""
+        bound = users.with_user(ctx.active_member_id)
+        resp = bound.scim_update_user_attribute(
+            attribute="title",
+            new_value="Bound Test Title",
+        )
+        assert resp.ok, f"Expected ok for bound user: {resp.data}"
+        _pause()
+
+        bound.scim_update_user_attribute(attribute="title", new_value="")
+        _pause()
+
     # ----- deactivated user -----
 
     def test_update_attribute_deactivated_user(self, ctx, users):

{slack_objects-0.1.0 → slack_objects-0.1.2}/tests/Smoke/users_smoke_test.py

@@ -110,17 +110,18 @@ def main() -> None:
         CallSpec("get_user_id_from_email(miss)", lambda: users.get_user_id_from_email("missing@example.com")),
 
         # Profile helpers
-        CallSpec("get_user_profile(bound)", lambda: bound.get_user_profile()),
+        CallSpec("get_user_profile()", lambda: bound.get_user_profile()),
         CallSpec("get_user_profile(by id)", lambda: users.get_user_profile("U1")),
-        CallSpec("set_user_profile_field(bound)", lambda: bound.set_user_profile_field("status_text", "hello")),
+        CallSpec("set_user_profile_field()", lambda: bound.set_user_profile_field("status_text", "hello")),
         CallSpec("set_user_profile_field(by id)", lambda: users.set_user_profile_field("status_text", "hello", user_id="U1")),
 
         # Classification helpers (need attributes)
         CallSpec("is_contingent_worker()", lambda: (_refresh_bound(), bound.is_contingent_worker())),
         CallSpec("is_guest()", lambda: (_refresh_bound(), bound.is_guest())),
         CallSpec("is_active()", lambda: (_refresh_bound(), bound.is_active())),
-        CallSpec("is_active(user_id override)", lambda: (_refresh_bound(), bound.is_active(user_id="U2"))),
+        CallSpec("is_active(by id)", lambda: (_refresh_bound(), bound.is_active(user_id="U2"))),
         CallSpec("is_active_scim()", lambda: bound.is_active_scim()),
+        CallSpec("is_active_scim(by id)", lambda: bound.is_active_scim(user_id="U1")),
 
         # Admin helpers
         CallSpec(
@@ -128,6 +129,7 @@ def main() -> None:
             lambda: bound.invite_user(channel_ids=["C1", "C2"], email="new@example.com", team_id="T1"),
         ),
         CallSpec("wipe_all_sessions()", lambda: bound.wipe_all_sessions()),
+        CallSpec("wipe_all_sessions(by id)", lambda: bound.wipe_all_sessions(user_id="U1")),
         CallSpec("add_to_workspace()", lambda: bound.add_to_workspace("U1", "T1")),
         CallSpec("remove_from_workspace()", lambda: bound.remove_from_workspace("U1", "T1")),
         CallSpec("add_to_conversation()", lambda: bound.add_to_conversation(["U1"], "C1")),
@@ -152,24 +154,34 @@ def main() -> None:
             "set_guest_expiration_date()",
             lambda: bound.set_guest_expiration_date("2030-01-01", workspace_id="T1"),
         ),
+        CallSpec(
+            "set_guest_expiration_date(by id)",
+            lambda: bound.set_guest_expiration_date("2030-01-01", user_id="U1", workspace_id="T1"),
+        ),
 
         # SCIM helpers (scim_version now comes from cfg, not a kwarg)
         CallSpec("scim_create_user()", lambda: bound.scim_create_user("testuser", "test@example.com")),
         CallSpec("scim_deactivate_user()", lambda: bound.scim_deactivate_user("U1")),
         CallSpec("scim_reactivate_user()", lambda: bound.scim_reactivate_user()),
+        CallSpec("scim_reactivate_user(by id)", lambda: bound.scim_reactivate_user(user_id="U1")),
         CallSpec(
-            "scim_update_user_attribute()",
+            "scim_update_user_attribute(by id)",
             lambda: bound.scim_update_user_attribute(user_id="U1", attribute="active", new_value=False),
         ),
+        CallSpec(
+            "scim_update_user_attribute()",
+            lambda: bound.scim_update_user_attribute(attribute="active", new_value=False),
+        ),
         CallSpec(
             "scim_update_email(by id)",
             lambda: bound.scim_update_email(user_id="U1", new_email="newemail@example.com"),
         ),
         CallSpec(
-            "scim_update_email(bound)",
+            "scim_update_email()",
             lambda: bound.scim_update_email(new_email="newemail@example.com"),
         ),
         CallSpec("make_multi_channel_guest()", lambda: bound.make_multi_channel_guest()),
+        CallSpec("make_multi_channel_guest(by id)", lambda: bound.make_multi_channel_guest(user_id="U1")),
 
         # SCIM search primitives
         CallSpec("scim_search_user_by_email()", lambda: bound.scim_search_user_by_email("test@example.com")),

{slack_objects-0.1.0 → slack_objects-0.1.2}/tests/UnitTests/users_unit_test.py

@@ -573,3 +573,93 @@ class TestScimUpdateEmail:
         users = _make_users()
         with pytest.raises(ValueError):
             users.scim_update_email(user_id="", new_email="x@example.com")
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# scim_update_user_attribute
+# ═══════════════════════════════════════════════════════════════════════════
+
+class TestScimUpdateUserAttribute:
+    """scim_update_user_attribute — version-aware SCIM PATCH for scalar attributes."""
+
+    def test_v2_payload_structure(self):
+        """v2 uses PatchOp schema with replace operation."""
+        users = _make_users()
+        bound = users.with_user("U1")
+        bound._scim_request = MagicMock(
+            return_value=ScimResponse(ok=True, status_code=200, data={}, text=""),
+        )
+        bound.scim_update_user_attribute(user_id="U1", attribute="active", new_value=False)
+
+        bound._scim_request.assert_called_once()
+        _, kwargs = bound._scim_request.call_args
+        op = kwargs["payload"]["Operations"][0]
+        assert op["op"] == "replace"
+        assert op["path"] == "active"
+        assert op["value"] is False
+
+    def test_v1_payload_structure(self):
+        """v1 sets attribute directly on payload root."""
+        users = _make_users()
+        bound = users.with_user("U1")
+        object.__setattr__(bound.cfg, "scim_version", "v1")
+        bound._scim_request = MagicMock(
+            return_value=ScimResponse(ok=True, status_code=200, data={}, text=""),
+        )
+        bound.scim_update_user_attribute(user_id="U1", attribute="active", new_value=False)
+
+        bound._scim_request.assert_called_once()
+        _, kwargs = bound._scim_request.call_args
+        assert kwargs["payload"]["active"] is False
+
+    def test_falls_back_to_bound_user_id(self):
+        """Omitting user_id uses self.user_id."""
+        users = _make_users()
+        bound = users.with_user("U1")
+        bound._scim_request = MagicMock(
+            return_value=ScimResponse(ok=True, status_code=200, data={}, text=""),
+        )
+        bound.scim_update_user_attribute(attribute="displayName", new_value="Alice")
+
+        bound._scim_request.assert_called_once()
+        _, kwargs = bound._scim_request.call_args
+        assert kwargs["path"] == "Users/U1"
+
+    def test_explicit_user_id_overrides_bound(self):
+        """Passing user_id explicitly takes precedence over bound user_id."""
+        users = _make_users()
+        bound = users.with_user("U_IGNORED")
+        bound._scim_request = MagicMock(
+            return_value=ScimResponse(ok=True, status_code=200, data={}, text=""),
+        )
+        bound.scim_update_user_attribute(user_id="U_OTHER", attribute="active", new_value=True)
+
+        bound._scim_request.assert_called_once()
+        _, kwargs = bound._scim_request.call_args
+        assert kwargs["path"] == "Users/U_OTHER"
+
+    def test_no_user_id_raises(self):
+        """Unbound instance with no user_id raises ValueError."""
+        users = _make_users()
+        with pytest.raises(ValueError, match="requires user_id"):
+            users.scim_update_user_attribute(attribute="active", new_value=False)
+
+    def test_invalid_scim_version_raises(self):
+        """Unsupported scim_version raises NotImplementedError."""
+        users = _make_users()
+        bound = users.with_user("U1")
+        object.__setattr__(bound.cfg, "scim_version", "v99")
+        with pytest.raises(NotImplementedError, match="Invalid SCIM version"):
+            bound.scim_update_user_attribute(attribute="active", new_value=False)
+
+    def test_invalid_user_id_raises(self):
+        """Path-traversal user_id is rejected by validate_scim_id."""
+        users = _make_users()
+        with pytest.raises(ValueError):
+            users.scim_update_user_attribute(user_id="../../bad", attribute="active", new_value=False)
+
+    def test_empty_user_id_raises(self):
+        """Empty user_id is rejected by validate_scim_id."""
+        users = _make_users()
+        with pytest.raises(ValueError):
+            users.scim_update_user_attribute(user_id="", attribute="active", new_value=False)

slack_objects-0.1.0/.github/copilot-instructions.md

@@ -1,5 +0,0 @@
-# Copilot Instructions
-
-## Project Guidelines
-- Follow Unix philosophy: build small, composable functions where higher-level methods leverage lower-level primitives. Don't mix concerns (e.g., don't embed identifier resolution inside a SCIM CRUD method). Keep signatures consistent across sibling methods.
-- Prefer consistency with the `Users.is_active`/`is_active_scim` pattern when structuring related methods (separate explicit SCIM method from higher-level orchestration).

slack_objects-0.1.0/src/slack_objects/_version.py

@@ -1,34 +0,0 @@
-# file generated by setuptools-scm
-# don't change, don't track in version control
-
-__all__ = [
-    "__version__",
-    "__version_tuple__",
-    "version",
-    "version_tuple",
-    "__commit_id__",
-    "commit_id",
-]
-
-TYPE_CHECKING = False
-if TYPE_CHECKING:
-    from typing import Tuple
-    from typing import Union
-
-    VERSION_TUPLE = Tuple[Union[int, str], ...]
-    COMMIT_ID = Union[str, None]
-else:
-    VERSION_TUPLE = object
-    COMMIT_ID = object
-
-version: str
-__version__: str
-__version_tuple__: VERSION_TUPLE
-version_tuple: VERSION_TUPLE
-commit_id: COMMIT_ID
-__commit_id__: COMMIT_ID
-
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
-
-__commit_id__ = commit_id = 'gf712fe717'