slack-objects 0.0.post31__py3-none-any.whl

slack_objects/workspaces.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+"""
+slack_objects.workspaces
+=======================
+
+Workspaces helper for the `slack-objects` package.
+
+Merged/refactored from two legacy implementations:
+- A "single-workspace" helper that fetches attributes via `team.info` (PCbot) :contentReference[oaicite:2]{index=2}
+- A "grid admin" helper that lists workspaces and can list workspace users/admins via admin endpoints :contentReference[oaicite:3]{index=3}
+
+Design goals:
+- Factory-friendly: `workspaces = slack.workspaces()` or `ws = slack.workspaces("T123")`
+- Modularity: public methods call wrapper methods; wrappers are the only place that directly call Slack API
+- Usability: supports both "work with one workspace" and "work with many workspaces in a grid"
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from .base import SlackObjectBase
+from .config import RateTier
+
+
+@dataclass
+class Workspaces(SlackObjectBase):
+    """
+    Workspaces domain helper.
+
+    Factory-style usage:
+        slack = SlackObjectsClient(cfg)
+        workspaces = slack.workspaces()             # unbound (grid/listing helpers)
+        ws = slack.workspaces("T12345678")          # bound to workspace_id
+
+    Notes:
+    - `workspace_id` is optional. Methods that require a workspace will enforce it.
+    - `workspaces_cache` is an optional cached list of workspaces (from admin.teams.list).
+      This enables fast name<->id lookups without re-fetching each time.
+    """
+    workspace_id: Optional[str] = None
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+    # Cache of workspaces returned by admin.teams.list (list of dicts with at least id/name)
+    workspaces_cache: List[Dict[str, Any]] = field(default_factory=list)
+
+    # ---------- factory helpers ----------
+
+    def with_workspace(self, workspace_id: str) -> "Workspaces":
+        """Return a new Workspaces instance bound to workspace_id, sharing cfg/client/logger/api."""
+        return Workspaces(
+            cfg=self.cfg,
+            client=self.client,
+            logger=self.logger,
+            api=self.api,
+            workspace_id=workspace_id,
+            workspaces_cache=self.workspaces_cache,
+        )
+
+    # ---------- attribute lifecycle ----------
+
+    def refresh(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Refresh attributes for workspace_id (or self.workspace_id) using team.info.
+
+        This method is intentionally layered: it calls `get_workspace_info()`.
+        """
+        if workspace_id:
+            self.workspace_id = workspace_id
+        if not self.workspace_id:
+            raise ValueError("refresh() requires workspace_id (passed or already set)")
+
+        resp = self.get_workspace_info(self.workspace_id)
+        if not resp.get("ok"):
+            raise RuntimeError(f"Workspaces.get_workspace_info() failed: {resp}")
+
+        # `team.info` returns `team` on success in the legacy version :contentReference[oaicite:4]{index=4}
+        self.attributes = resp.get("team") or {}
+        return self.attributes
+
+    def _require_workspace_id(self, workspace_id: Optional[str] = None) -> str:
+        """Return a workspace_id or raise, used by methods that require one."""
+        wid = workspace_id or self.workspace_id
+        if not wid:
+            raise ValueError("This operation requires a workspace_id (passed or bound).")
+        return wid
+
+    # ============================================================
+    # Slack API wrapper layer
+    # ============================================================
+    # Only these methods should call `self.api.call(...)` directly.
+
+    def _team_info(self, workspace_id: str) -> Dict[str, Any]:
+        """Wrapper for team.info (fetch a workspace's metadata)."""
+        return self.api.call(self.client, "team.info", rate_tier=RateTier.TIER_3, team=workspace_id)
+
+    def _admin_teams_list(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Wrapper for admin.teams.list (Grid: list workspaces)."""
+        return self.api.call(self.client, "admin.teams.list", rate_tier=RateTier.TIER_3, **payload)
+
+    def _admin_users_list(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Wrapper for admin.users.list (list users in a workspace)."""
+        return self.api.call(self.client, "admin.users.list", rate_tier=RateTier.TIER_4, **payload)
+
+    def _admin_teams_admins_list(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """Wrapper for admin.teams.admins.list (list admin IDs for a workspace)."""
+        return self.api.call(self.client, "admin.teams.admins.list", rate_tier=RateTier.TIER_3, **payload)
+
+    # ============================================================
+    # Public API (calls wrappers above)
+    # ============================================================
+
+    def get_workspace_info(self, workspace_id: str) -> Dict[str, Any]:
+        """Public method for team.info."""
+        return self._team_info(workspace_id)
+
+    def list_workspaces(self, *, force_refresh: bool = False) -> List[Dict[str, Any]]:
+        """
+        Return a list of workspaces in the Enterprise Grid (admin.teams.list), paginated.
+
+        This replaces the legacy constructor-side fetching of all workspaces :contentReference[oaicite:5]{index=5}.
+        Results are cached in `workspaces_cache` unless `force_refresh=True`.
+        """
+        if self.workspaces_cache and not force_refresh:
+            return self.workspaces_cache
+
+        workspaces: List[Dict[str, Any]] = []
+        payload: Dict[str, Any] = {}
+
+        while True:
+            resp = self._admin_teams_list(payload)
+            if not resp.get("ok"):
+                raise RuntimeError(f"admin.teams.list failed: {resp}")
+
+            teams = resp.get("teams") or []
+            workspaces.extend(teams)
+
+            # Slack commonly returns cursor pagination via response_metadata.next_cursor
+            meta = resp.get("response_metadata") or {}
+            cursor = meta.get("next_cursor") or ""
+            if cursor:
+                payload["cursor"] = cursor
+            else:
+                break
+
+        self.workspaces_cache = workspaces
+        return workspaces
+
+    # ----- name/id resolution helpers (from legacy SlackAdmin) -----
+
+    def get_workspace_name(self, workspace_id: str, *, force_refresh: bool = False) -> str:
+        """
+        Resolve a workspace ID -> workspace name using the cached list from admin.teams.list.
+
+        Legacy behavior raised if not found :contentReference[oaicite:6]{index=6}.
+        """
+        workspaces = self.list_workspaces(force_refresh=force_refresh)
+        for ws in workspaces:
+            if ws.get("id") == workspace_id:
+                name = ws.get("name")
+                if name:
+                    return str(name)
+
+        raise ValueError(
+            f"Could not find a workspace with id '{workspace_id}'. "
+            "Check the id/token scopes and ensure you are targeting the correct Grid."
+        )
+
+    def get_workspace_id(self, workspace_name: str, *, force_refresh: bool = False) -> str:
+        """
+        Resolve a workspace name -> workspace ID using the cached list from admin.teams.list.
+
+        Legacy behavior raised if not found :contentReference[oaicite:7]{index=7}.
+        """
+        workspaces = self.list_workspaces(force_refresh=force_refresh)
+        target = workspace_name.strip().lower()
+
+        for ws in workspaces:
+            if str(ws.get("name", "")).strip().lower() == target:
+                wid = ws.get("id")
+                if wid:
+                    return str(wid)
+
+        raise ValueError(
+            f"Could not find a workspace with name '{workspace_name}'. "
+            "Check the name/token scopes and ensure you are targeting the correct Grid."
+        )
+
+    def get_workspace_from_name(self, workspace_name: str, *, force_refresh: bool = False) -> Dict[str, Any]:
+        """
+        Return the workspace dict that matches the provided name.
+
+        Legacy behavior raised if not found :contentReference[oaicite:8]{index=8}.
+        """
+        workspaces = self.list_workspaces(force_refresh=force_refresh)
+        target = workspace_name.strip().lower()
+
+        for ws in workspaces:
+            if str(ws.get("name", "")).strip().lower() == target:
+                return ws
+
+        raise ValueError(
+            f"Could not find a workspace with name '{workspace_name}'. "
+            "Check the name/token scopes and ensure you are targeting the correct Grid."
+        )
+
+    # ----- workspace membership helpers (from legacy SlackAdmin) -----
+
+    def list_users(self, workspace_id: Optional[str] = None) -> List[Dict[str, Any]]:
+        """
+        Return a list of users in a workspace via admin.users.list (paginated).
+
+        This matches the legacy behavior of returning `data['users']` across pages :contentReference[oaicite:9]{index=9}.
+        """
+        wid = self._require_workspace_id(workspace_id)
+
+        payload: Dict[str, Any] = {"team_id": wid}
+        users: List[Dict[str, Any]] = []
+
+        while True:
+            resp = self._admin_users_list(payload)
+            if not resp.get("ok"):
+                raise RuntimeError(f"admin.users.list failed: {resp}")
+
+            users.extend(resp.get("users") or [])
+
+            meta = resp.get("response_metadata") or {}
+            cursor = meta.get("next_cursor") or ""
+            if cursor:
+                payload["cursor"] = cursor
+            else:
+                break
+
+        return users
+
+    def list_admin_ids(self, workspace_id: Optional[str] = None) -> List[str]:
+        """
+        Return a list of admin user IDs for a workspace via admin.teams.admins.list (paginated).
+
+        Legacy version returned list_of_admins (IDs) :contentReference[oaicite:10]{index=10}.
+        """
+        wid = self._require_workspace_id(workspace_id)
+
+        payload: Dict[str, Any] = {"team_id": wid}
+        admin_ids: List[str] = []
+
+        while True:
+            resp = self._admin_teams_admins_list(payload)
+            if not resp.get("ok"):
+                raise RuntimeError(f"admin.teams.admins.list failed: {resp}")
+
+            admin_ids.extend([str(x) for x in (resp.get("admin_ids") or [])])
+
+            meta = resp.get("response_metadata") or {}
+            cursor = meta.get("next_cursor") or ""
+            if cursor:
+                payload["cursor"] = cursor
+            else:
+                break
+
+        return admin_ids

slack_objects-0.0.post31.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: slack-objects
+Version: 0.0.post31
+Summary: This package defines classes for working with slack objects like users, conversations, messages, etc.
+Author-email: "Marcos E. Mercado" <marcos_elias@hotmail.com>
+Keywords: slack,objects,classes,slack objects,utilities,slack utilities,slack object types,slack types,types
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: slack-sdk
+Requires-Dist: PC_Utils
+Dynamic: license-file
+
+# slack-objects
+
+A focused Python package for working with **Slack objects** commonly used in administration and automation workflows.
+
+The following Slack object types will be supported:
+
+- **Users**
+- **Conversations**
+- **Messages**
+- **Files**
+- **Workspaces**
+- **IDP_groups**
+
+
+---
+
+## Overview
+
+`slack-objects` provides lightweight, reusable classes that wrap Slack Web API, Admin API, and SCIM operations in a consistent, object-oriented way. It is designed for:
+
+- Slack administration automation
+- Identity and access management flows
+- Internal tooling and bots
+- Auditing and cleanup scripts
+
+The package does **not** aim to be a full Slack SDK replacement. Instead, it focuses on common higher-level tasks that typically require multiple API calls and boilerplate logic.
+
+---
+
+## Requirements
+
+- Python **3.9+**
+- Slack app with appropriate scopes
+- Tokens provided via environment variables or from Azure KeyVault using PC_Azure package (`python -m pip install PC_Azure`)
+
+Typical dependencies:
+- `slack_sdk`
+- `requests`
+- `python-dotenv` (optional)
+- `PC_Azure` (optional)
+
+---
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## Classes and usage
+
+### `Users`
+
+Purpose: actions related to Slack users.
+
+Constructor:
+```python
+Users(global_vars, client, logger, user_id="")
+```
+
+Key methods:
+- `is_contingent_worker()` → bool using name/display name label `[External]`.
+- `is_guest()` → bool if `is_restricted` or `is_ultra_restricted`.
+- `make_multi_channel_guest(token, scim_version='v1')` → `requests.Response` via SCIM (v1/v2).
+- `remove_from_channels(token, client, logger, channel_ids)` → remove user from channels (admin API).
+- `remove_from_workspaces(client, logger, workspace_ids, keep=[])` → remove user from workspaces.
+- `ap_studio_process()` → composite flow: convert to MCG, remove from org-wide channels, remove from other workspaces.
+- `get_userId_from_email(email)` → Slack user ID or empty string.
+- `is_user_authorized(service_name, auth_level='read')` → bool based on IdP group membership.
+- `invite_user(channel_ids, email, team_id, email_password_policy_enabled=False)` → invite a user, returns response string.
+
+Example:
+```python
+u = Users(global_vars, client, logger, user_id="U123")
+if u.is_contingent_worker():
+    u.make_multi_channel_guest(token=global_vars.user_token)
+```
+
+### `Conversations`
+
+Purpose: actions related to conversations (e.g., channels).
+
+Constructor:
+```python
+Conversations(global_vars, client, logger, channel_id)
+```
+
+Key methods:
+- `is_private()` → bool.
+- `get_messages(channel_id="", include_all_metadata=False, limit=None, inclusive=True, latest=None, oldest=None)` → list of messages using `conversations.history` with pagination.
+
+Example:
+```python
+ch = Conversations(global_vars, client, logger, channel_id="C123")
+msgs = ch.get_messages(limit=100)
+```
+
+### `Messages`
+
+Purpose: manage Slack messages and blocks.
+
+Constructor:
+```python
+Messages(global_vars, client, logger, channel_id, ts, message=None)
+```
+
+Key methods:
+- `update_message(as_user=True, channel_id="", message_ts="", new_message_blocks=[], new_message_text="", new_message_attachments="")` → update message via `chat.update`.
+- `replace_message_block(blocks=[], block_type="", block_id="", text="", new_block={}, new_block_id="")` → find a block by type or id and replace it, then update message.
+
+Example:
+```python
+msg = Messages(global_vars, client, logger, "C123", "1717000000.000100")
+msg.update_message(new_message_text="Updated content")
+```
+
+### `Files`
+
+Purpose: interact with files in Slack.
+
+Constructor:
+```python
+Files(global_vars, client, logger, file_id="", get_content=False)
+```
+
+Key methods:
+- `get_text_content()` → fetch content for text files via `url_private` (uses bot token).
+- `upload_to_slack(title, channel="", thread_ts="")` → upload the current file content via `files_upload_v2`.
+- `delete_file(file_id="")` → delete a file by id.
+- `list_files(**args)` → simple wrapper around `files.list`.
+- `get_file_source_message(channel: Channels, file_id="", user_id="")` → find the message where a file was shared (looks back ~5 messages).
+
+Example:
+```python
+f = Files(global_vars, client, logger, file_id="F123", get_content=True)
+f.upload_to_slack(title="Processed file", channel="C123")
+```
+
+### `Workspaces`
+
+Purpose: workspace info helper.
+
+Constructor:
+```python
+Workspaces(client, logger, workspace_id)
+```
+
+Obtains attributes via `team.info`.
+
+### `IDP_groups`
+
+Purpose: manage IdP (Okta) groups via SCIM.
+
+Constructor:
+```python
+IDP_groups(global_vars)
+```
+
+Key methods:
+- `get_groups()` → list of `{ 'group id', 'group name' }` (paginated).
+- `get_members(group_id)` → list of members with `value` (user id) and `display` (name).
+- `is_member(user_id, group_id)` → bool.
+
+Example:
+```python
+idp = IDP_groups(global_vars)
+if idp.is_member("U123", "GP456"):
+    print("authorized")
+```
+
+## Tokens and rate limits
+
+- Methods that call admin or SCIM APIs require the User OAuth token.
+- Standard Web API calls may use the Bot token via `App.client`.
+- Some methods respect internal wait times (e.g., `Tier_2`, `Tier_3`, `Tier_4`) to avoid rate limits. Configure these in `libraries_and_globals.py`.
+
+## Error handling
+
+- Methods catch `SlackApiError` and log messages via the provided `logger`.
+- Some methods post audit logs to channels configured in `global_vars`.
+
+## Notes
+
+- SCIM version: production uses `v1`, sandbox may use `v2`.
+- `Files.get_text_content()` is designed for `text/*` mimetypes.

slack_objects-0.0.post31.dist-info/RECORD

@@ -0,0 +1,18 @@
+slack_objects/__init__.py,sha256=wYczk9CK67k2nrq8rtlxVqGMu_93wBNGIf_Ha-GH5mE,525
+slack_objects/_version.py,sha256=SjQ_icTK6fnX32Dc0GVEVLmDoZTtEN7KhTlrIniW_QY,750
+slack_objects/api_caller.py,sha256=Gch_DFpAgQN7Svgoe9Y4F4R2FY4PfiBchXuGbZ0sOgw,1507
+slack_objects/base.py,sha256=mCKi5u1apj1vQTuNwlIcFf-A4Yh_Ag3lTp6kXJVJa3s,1097
+slack_objects/client.py,sha256=K3Ln6SGkgfc9i2IVIvFlcowX8Cgp2E26RnKf7XRr46k,1966
+slack_objects/config.py,sha256=Pe_5SGXNvbZEgKYA6DdsQYpGl1Uod2m41K385QI_ib0,809
+slack_objects/conversations.py,sha256=ySJqUixCKQKkUPd-_6AeFO99uYyNq4qscqpkZ1OzRbs,17837
+slack_objects/files.py,sha256=g6LnP1pWpEKmHeClF6IusABrKY4nSKyZxI0X8NXnEbg,12540
+slack_objects/idp_groups.py,sha256=Jf2Sr6PIO-avgbbt6iJT_g7Qdrzs_Yxz0jd6C8YDTWo,7778
+slack_objects/messages.py,sha256=PsUSqUfX5gtAwl7BKusT1AnTLqKRJgz4bkuXc1W4If4,11978
+slack_objects/rate_limits.py,sha256=cSfG9k04DlpyOQRb8r5IFquKfgbrAEQHX4G9oGd8QcE,1496
+slack_objects/users.py,sha256=BvLYy-Ng82Mv5pnIPS_eF6hYXk-6upeEsMq-9QrTCG8,22315
+slack_objects/workspaces.py,sha256=1yUWIca61fq1OwB6xMJZJFCLh7HNmpku4vhjhvCJg-A,10744
+slack_objects-0.0.post31.dist-info/licenses/LICENSE,sha256=gIj0uwoGs4CwZR0bAP1ZP-F6B5f7VWJDz3Kfpc3c0dI,1090
+slack_objects-0.0.post31.dist-info/METADATA,sha256=gaqROB2GRuwm8FJ6O5GzLOOs7Wddg2HmXg3buGpC0-k,6379
+slack_objects-0.0.post31.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+slack_objects-0.0.post31.dist-info/top_level.txt,sha256=enSaCqZ69Tu_AzK_F0_NEtvRK-r5OjpMHJsnFh5Z8Wo,14
+slack_objects-0.0.post31.dist-info/RECORD,,

slack_objects-0.0.post31.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

slack_objects-0.0.post31.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Mercado
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

slack_objects-0.0.post31.dist-info/top_level.txt

@@ -0,0 +1 @@
+slack_objects