slack-objects 0.0.2.dev0__tar.gz → 0.0.3__tar.gz

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/.gitignore

@@ -16,4 +16,5 @@
 # Python packaging artifacts
 dist/
 build/
-*.egg-info/
+*.egg-info/
+src/slack_objects/_version.py

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-objects
-Version: 0.0.2.dev0
+Version: 0.0.3
 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
@@ -10,9 +10,9 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: slack-sdk
-Requires-Dist: PC_Utils
-Requires-Dist: requests
+Requires-Dist: slack-sdk<4,>=3.27
+Requires-Dist: PC_Utils>=0.1
+Requires-Dist: requests<3,>=2.31
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: build; extra == "dev"
@@ -67,8 +67,9 @@ Instead, it focuses on higher-level object operations that typically require:
 All object helpers are created from a single entry point:
 
 ```python
-from slack_objects.client import SlackObjectsClient
+from slack_objects import SlackObjectsClient, SlackObjectsConfig
 
+cfg = SlackObjectsConfig(bot_token="xoxb-...", user_token="xoxp-...", scim_token="xoxp-...", ...)
 slack = SlackObjectsClient(cfg)
 
 users = slack.users()
@@ -157,6 +158,6 @@ python -m tests.run_all_smoke
 
 ## Notes
 
-- SCIM v1 is the default; v2 is supported where applicable
-- Guest expiration dates use `PC_Utils.Datetime` if installed
+- SCIM v2 is the default; v1 is supported where applicable
+- `PC_Utils` is a required dependency (used for datetime handling, e.g., guest expiration dates)
 - This package is intended for automation and administration workflows

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/README.md

@@ -46,8 +46,9 @@ Instead, it focuses on higher-level object operations that typically require:
 All object helpers are created from a single entry point:
 
 ```python
-from slack_objects.client import SlackObjectsClient
+from slack_objects import SlackObjectsClient, SlackObjectsConfig
 
+cfg = SlackObjectsConfig(bot_token="xoxb-...", user_token="xoxp-...", scim_token="xoxp-...", ...)
 slack = SlackObjectsClient(cfg)
 
 users = slack.users()
@@ -136,6 +137,6 @@ python -m tests.run_all_smoke
 
 ## Notes
 
-- SCIM v1 is the default; v2 is supported where applicable
-- Guest expiration dates use `PC_Utils.Datetime` if installed
+- SCIM v2 is the default; v1 is supported where applicable
+- `PC_Utils` is a required dependency (used for datetime handling, e.g., guest expiration dates)
 - This package is intended for automation and administration workflows

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/pyproject.toml

@@ -24,9 +24,9 @@ classifiers=[
 keywords = ["slack", "objects", "classes", "slack objects", "utilities", "slack utilities", "slack object types", "slack types", "types"]
 
 dependencies = [
-"slack-sdk",
-"PC_Utils",
-"requests",
+    "slack-sdk>=3.27,<4",
+    "PC_Utils>=0.1",
+    "requests>=2.31,<3",
 ]
 
 [project.optional-dependencies]

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/src/slack_objects/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.0.2.dev0'
-__version_tuple__ = version_tuple = (0, 0, 2, 'dev0')
+__version__ = version = '0.0.3'
+__version_tuple__ = version_tuple = (0, 0, 3)
 
-__commit_id__ = commit_id = 'ga1f28b971'
+__commit_id__ = commit_id = 'g51cb2b9df'

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/src/slack_objects/api_caller.py

@@ -17,7 +17,8 @@ class SlackApiCaller:
         self.cfg = cfg
         self.policy = policy
 
-    def call(self, client, method: str, *, rate_tier: Optional[RateTier] = None, use_json: bool = False, **kwargs) -> dict:
+    def call(self, client, method: str, *, rate_tier: Optional[RateTier] = None, use_json: bool = False, _retry_count: int = 0, **kwargs) -> dict:
+        MAX_RETRIES = 5
         tier = rate_tier or self.policy.tier_for(method) or self.cfg.default_rate_tier
 
         try:
@@ -27,16 +28,17 @@ class SlackApiCaller:
                 resp = client.api_call(method, params=kwargs)
 
             data = resp.data if hasattr(resp, "data") else resp
-
-            # Space out subsequent calls
             time.sleep(float(tier))
             return data
 
         except SlackApiError as e:
-            # Handle rate limiting properly
             if e.response is not None and e.response.status_code == 429:
-                retry_after = int(e.response.headers.get("Retry-After", tier))
+                if _retry_count >= MAX_RETRIES:
+                    raise RuntimeError(f"Rate-limited {MAX_RETRIES} times on {method}; giving up.") from e
+                try:
+                    retry_after = int(e.response.headers.get("Retry-After", tier))
+                except (ValueError, TypeError):
+                    retry_after = int(float(tier))
                 time.sleep(retry_after)
-                return self.call(client, method, rate_tier=tier, **kwargs)
-
+                return self.call(client, method, rate_tier=tier, use_json=use_json, _retry_count=_retry_count + 1, **kwargs)
             raise

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/src/slack_objects/base.py

@@ -7,6 +7,25 @@ from .api_caller import SlackApiCaller
 from .config import SlackObjectsConfig
 
 
+# Keys that are safe to include in error messages (never contain tokens)
+_SAFE_ERROR_KEYS = frozenset({"ok", "error", "needed", "provided", "response_metadata"})
+
+
+def safe_error_context(resp: Any, *, max_len: int = 300) -> str:
+    """
+    Return a truncated, token-free summary of an API response for use in exception messages.
+
+    Only well-known diagnostic keys are kept. The result is capped at *max_len* characters
+    to prevent massive payloads from flooding logs or error-tracking systems.
+    """
+    if isinstance(resp, dict):
+        summary = {k: v for k, v in resp.items() if k in _SAFE_ERROR_KEYS}
+    else:
+        summary = repr(resp)
+    text = str(summary)
+    return text[:max_len] + ("..." if len(text) > max_len else "")
+
+
 @dataclass
 class SlackObjectBase:
     """

slack_objects-0.0.3/src/slack_objects/config.py

@@ -0,0 +1,57 @@
+from enum import Enum
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+class RateTier(float, Enum):
+	"""
+	Slack API rate-tier backoff defaults (seconds). These are defined to conform to Slack Web API rate limits.
+	https://docs.slack.dev/apis/web-api/rate-limits/
+	"""
+
+	TIER_1 = 60.0	# 1+ per minute
+	TIER_2 = 3.0	# 20+ per minute
+	TIER_3 = 1.2	# 50+ per minute
+	TIER_4 = 0.6	# 100+ per minute
+
+
+@dataclass(frozen=True)
+class SlackObjectsConfig:
+	"""
+	Configuration settings for slack-objects.
+
+	Tokens are optional at construction time.
+	Individual methods will raise clear errors if a required token is missing.
+	"""
+	bot_token: Optional[str] = field(default=None, repr=False)
+	user_token: Optional[str] = field(default=None, repr=False)
+	scim_token: Optional[str] = field(default=None, repr=False)
+
+	default_rate_tier: RateTier = RateTier.TIER_2
+
+	auth_idp_groups_read_access: dict[str, list[str]] = field(default_factory=dict)
+	auth_idp_groups_write_access: dict[str, list[str]] = field(default_factory=dict)
+
+	# SCIM settings
+	scim_base_url: str = "https://api.slack.com/scim"
+	scim_version: str = "v2"
+
+	# HTTP timeout for SCIM and file-download requests (seconds)
+	http_timeout_seconds: int = 30
+
+	def __repr__(self) -> str:
+		""" Modifying the default dataclass __repr__ to mask token values for security. """
+		def _mask(val: Optional[str]) -> str:
+			return "***" if val else "None"
+		return (
+			f"SlackObjectsConfig("
+			f"bot_token={_mask(self.bot_token)}, "
+			f"user_token={_mask(self.user_token)}, "
+			f"scim_token={_mask(self.scim_token)}, "
+			f"default_rate_tier={self.default_rate_tier}, "
+			f"auth_idp_groups_read_access={self.auth_idp_groups_read_access}, "
+			f"auth_idp_groups_write_access={self.auth_idp_groups_write_access}, "
+			f"scim_base_url={self.scim_base_url}, "
+			f"scim_version={self.scim_version}, "
+			f"http_timeout_seconds={self.http_timeout_seconds})"
+		)

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/src/slack_objects/conversations.py

@@ -33,7 +33,7 @@ from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional, Sequence, Union
 
 
-from .base import SlackObjectBase
+from .base import SlackObjectBase, safe_error_context
 from .config import RateTier
 from .messages import Messages
 
@@ -75,7 +75,7 @@ class Conversations(SlackObjectBase):
 
         resp = self.get_conversation_info(self.channel_id)
         if not resp.get("ok"):
-            raise RuntimeError(f"Conversations.get_conversation_info() failed: {resp}")
+            raise RuntimeError(f"Conversations.get_conversation_info() failed: {safe_error_context(resp)}")
 
         self.attributes = resp.get("channel") or {}
         return self.attributes

{slack_objects-0.0.2.dev0 → slack_objects-0.0.3}/src/slack_objects/idp_groups.py

@@ -17,7 +17,7 @@ This module implements the following functionality:
 
 Design decisions
 ----------------
-- SCIM REST calls are centralized in `_scim_request()`; all public methods call those wrappers (keeps code modular and testable).
+- 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.
 """
@@ -25,16 +25,14 @@ Design decisions
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 
-import json
-import time
 import requests
 
 from .base import SlackObjectBase
-from .config import RateTier
+from .scim_base import ScimMixin, ScimResponse, validate_scim_id
 
 
 @dataclass
-class IDP_groups(SlackObjectBase):
+class IDP_groups(ScimMixin, SlackObjectBase):
     """
     IdP (SCIM) groups helper.
 
@@ -60,78 +58,26 @@ class IDP_groups(SlackObjectBase):
             scim_session=self.scim_session,
         )
 
-    # ---------- SCIM request wrapper ----------
-    def _scim_base_url(self, scim_version: str) -> str:
-        """Return configurable SCIM base URL; default to Slack SCIM endpoints when not overridden."""
-        if scim_version == "v2" and getattr(self.cfg, "scim_base_url_v2", None):
-            return self.cfg.scim_base_url_v2.rstrip("/") + "/"
-        if scim_version == "v1" and getattr(self.cfg, "scim_base_url_v1", None):
-            return self.cfg.scim_base_url_v1.rstrip("/") + "/"
-        return f"https://api.slack.com/scim/{scim_version}/"
-
-    def _scim_request(
-        self,
-        *,
-        path: str,
-        method: str = "GET",
-        payload: Optional[Dict[str, Any]] = None,
-        scim_version: str = "v1",
-        token: Optional[str] = None,
-        params: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """
-        Low-level SCIM request. Returns parsed JSON dict.
-
-        It raises ValueError when token is missing. Network/HTTP errors will raise requests exceptions.
-        We add a small sleep based on RateTier to reduce burstiness (keeps legacy cautious behavior).
-        """
-        tok = token or getattr(self.cfg, "scim_token", None)
-        if not tok:
-            raise ValueError("SCIM request requires cfg.scim_token (or token override)")
-
-        # conservative sleep to avoid bursts (can be tuned)
-        time.sleep(float(RateTier.TIER_2))
-
-        url = self._scim_base_url(scim_version) + path.lstrip("/")
-        headers = {
-            "Authorization": f"Bearer {tok}",
-            "Content-Type": "application/json; charset=utf-8",
-        }
-
-        resp = self.scim_session.request(
-            method=method.upper(),
-            url=url,
-            headers=headers,
-            params=params,
-            json=payload,
-            timeout=getattr(self.cfg, "http_timeout_seconds", 30),
-        )
-        resp.raise_for_status()
-        # best-effort JSON parse; return empty dict if no body
-        try:
-            return resp.json() if resp.text else {}
-        except Exception:
-            return {"_raw_text": resp.text or ""}
-
     # ---------- endpoint wrappers (only these call _scim_request) ----------
 
-    def _scim_groups_list(self, *, count: int = 1000, start_index: Optional[int] = None, scim_version: str = "v1") -> Dict[str, Any]:
+    def _scim_groups_list(self, *, count: int = 1000, start_index: Optional[int] = None) -> Dict[str, Any]:
         """
         Wrapper for GET Groups (paginated).
         Accepts pagination params as query parameters according to Slack SCIM docs.
         """
-        params = {"count": count}
+        params: Dict[str, Any] = {"count": count}
         if start_index:
             params["startIndex"] = start_index
-        return self._scim_request(path="Groups", method="GET", params=params, scim_version=scim_version)
+        return self._scim_request(path="Groups", method="GET", params=params).data
 
-    def _scim_group_get(self, group_id: str, scim_version: str = "v1") -> Dict[str, Any]:
+    def _scim_group_get(self, group_id: str) -> Dict[str, Any]:
         """Wrapper for GET Groups/{id}"""
-        return self._scim_request(path=f"Groups/{group_id}", method="GET", scim_version=scim_version)
+        validate_scim_id(group_id, "group_id")
+        return self._scim_request(path=f"Groups/{group_id}", method="GET").data
 
     # ---------- public helpers ----------
 
-    def get_groups(self, scim_version: str = "v1", fetch_count: int = 1000) -> List[Dict[str, str]]:
+    def get_groups(self, fetch_count: int = 1000) -> List[Dict[str, str]]:
         """
         Return a list of IdP groups visible to the SCIM token.
 
@@ -147,7 +93,7 @@ class IDP_groups(SlackObjectBase):
         retrieved = 0
 
         while True:
-            resp = self._scim_groups_list(count=fetch_count, start_index=start_index, scim_version=scim_version)
+            resp = self._scim_groups_list(count=fetch_count, start_index=start_index)
 
             # Slack SCIM returns 'Resources' (list) and 'totalResults' and 'startIndex' values.
             resources = resp.get("Resources", []) or []
@@ -173,7 +119,7 @@ class IDP_groups(SlackObjectBase):
 
         return groups_out
 
-    def get_members(self, group_id: Optional[str] = None, scim_version: str = "v1") -> List[Dict[str, str]]:
+    def get_members(self, group_id: Optional[str] = None) -> List[Dict[str, str]]:
         """
         Return the members of a group as a list of dicts `{'value': <user_id>, 'display': <name>}`.
 
@@ -183,16 +129,16 @@ class IDP_groups(SlackObjectBase):
         if not gid:
             raise ValueError("get_members requires group_id (passed or bound)")
 
-        resp = self._scim_group_get(gid, scim_version=scim_version)
+        resp = self._scim_group_get(gid)
         # In the legacy scripts, group members are at `members` in the response body
         return resp.get("members", [])
 
-    def is_member(self, user_id: str, group_id: Optional[str] = None, scim_version: str = "v1") -> bool:
+    def is_member(self, user_id: str, group_id: Optional[str] = None) -> bool:
         """
         Return True if `user_id` is a member of `group_id`.
         Preserves legacy semantics (scans the members list).
         """
-        members = self.get_members(group_id=group_id, scim_version=scim_version)
+        members = self.get_members(group_id=group_id)
         for member in members:
             # member dicts historically had 'value' for id
             if member.get("value") == user_id:

slack_objects-0.0.3/src/slack_objects/scim_base.py

@@ -0,0 +1,106 @@
+"""
+Shared SCIM plumbing for any object helper that makes SCIM REST calls.
+
+Centralizes:
+- ID validation (path-injection defense)
+- Base URL construction
+- Token-guarded HTTP request + JSON parsing
+- Rate-tier sleep
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+import requests
+
+from .config import RateTier
+
+# Slack IDs are alphanumeric with hyphens/underscores.
+_SLACK_ID_RE = re.compile(r"^[A-Za-z0-9_\-]+$")
+
+
+def validate_scim_id(value: str, label: str = "id") -> str:
+    """Raise ValueError if *value* contains path-traversal or unexpected characters."""
+    if not value or not _SLACK_ID_RE.match(value):
+        raise ValueError(f"Invalid {label}: {value!r}")
+    return value
+
+
+@dataclass
+class ScimResponse:
+    """Structured result for SCIM calls (no Slack 'ok' boolean)."""
+    ok: bool
+    status_code: int
+    data: Dict[str, Any]
+    text: str
+
+
+class ScimMixin:
+    """
+    Mixin providing SCIM REST helpers.
+
+    Requirements on the host class (satisfied by SlackObjectBase subclasses):
+        - self.cfg   (SlackObjectsConfig)
+        - self.scim_session  (requests.Session)
+    """
+
+    # --- URL ---
+
+    def _scim_base_url(self) -> str:
+        return f"{self.cfg.scim_base_url.rstrip('/')}/{self.cfg.scim_version}/"
+
+    # --- Low-level request ---
+
+    def _scim_request(
+        self,
+        *,
+        path: str,
+        method: str = "GET",
+        payload: Optional[Dict[str, Any]] = None,
+        token: Optional[str] = None,
+        params: Optional[Dict[str, Any]] = None,
+        raise_for_status: bool = True,
+    ) -> ScimResponse:
+        """
+        Perform a SCIM REST request and return a ScimResponse.
+
+        Raises ValueError when the token is missing.
+        Raises requests.HTTPError on non-2xx when raise_for_status is True.
+        """
+        tok = token or self.cfg.scim_token
+        if not tok:
+            raise ValueError("SCIM request requires cfg.scim_token (or token override)")
+
+        url = self._scim_base_url() + path.lstrip("/")
+        headers = {
+            "Authorization": f"Bearer {tok}",
+            "Content-Type": "application/json; charset=utf-8",
+        }
+
+        resp = self.scim_session.request(
+            method=method.upper(),
+            url=url,
+            headers=headers,
+            params=params,
+            json=payload,
+            timeout=self.cfg.http_timeout_seconds,
+        )
+
+        if raise_for_status:
+            resp.raise_for_status()
+
+        text = resp.text or ""
+        try:
+            data = resp.json() if text else {}
+        except Exception:
+            data = {"_raw_text": text}
+
+        ok = resp.ok and (data.get("Errors") is None)
+
+        time.sleep(float(RateTier.TIER_2))
+        return ScimResponse(ok=ok, status_code=resp.status_code, data=data, text=text)