slack-objects 0.0.post31__tar.gz

slack_objects-0.0.post31/.gitignore

@@ -0,0 +1,14 @@
+################################################################################
+# This .gitignore file was automatically created by Microsoft(R) Visual Studio.
+################################################################################
+
+/.vs/slack-objects.slnx
+*.slnx
+*.pyproj
+/.vs/slack-objects/CopilotIndices/18.3.494.57194
+/src/slack_objects/__pycache__
+/.vs/CopilotSnapshots/*
+/.vs/CopilotIndices/*
+/.vs/slack-objects/CopilotIndices/*
+/.vs/slack-objects/CopilotIndices/*
+/tests/__pycache__

slack_objects-0.0.post31/.vs/VSWorkspaceState.json

@@ -0,0 +1,8 @@
+{
+  "ExpandedNodes": [
+    "",
+    "\\src",
+    "\\src\\slack-objects"
+  ],
+  "PreviewInSolutionExplorer": false
+}

slack_objects-0.0.post31/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,185 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools >= 77.0.3", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slack-objects"
+# version = "0.0.1"  # Remove any existing version parameter.
+dynamic = ["version"]
+authors = [
+{name="Marcos E. Mercado", email="marcos_elias@hotmail.com"},
+]
+description = "This package defines classes for working with slack objects like users, conversations, messages, etc."
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers=[
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]  # Update these accordingly
+keywords = ["slack", "objects", "classes", "slack objects", "utilities", "slack utilities", "slack object types", "slack types", "types"]
+dependencies = [
+"slack-sdk",
+"PC_Utils",
+]
+
+[tool.setuptools_scm]
+version_file = "src/slack_objects/_version.py"
+local_scheme = "no-local-version"
+version_scheme = "post-release"

slack_objects-0.0.post31/pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+pythonpath =
+    src

slack_objects-0.0.post31/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

slack_objects-0.0.post31/src/slack_objects/__init__.py

@@ -0,0 +1,22 @@
+from .client import SlackObjectsClient
+from .config import SlackObjectsConfig, RateTier #, IdPGroupConfig
+
+from .users import Users
+#from .conversations import Conversations
+#from .messages import Messages
+#from .files import Files
+#from .workspaces import Workspaces
+#from .idp_groups import IDP_groups
+
+__all__ = [
+    "SlackObjectsClient",
+    "SlackObjectsConfig",
+    "RateTier",
+    "IdPGroupConfig",
+    "Users",
+    "Channels",
+    "Messages",
+    "Files",
+    "Workspaces",
+    "IDP_groups",
+]

slack_objects-0.0.post31/src/slack_objects/_version.py

@@ -0,0 +1,34 @@
+# 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.0.post31'
+__version_tuple__ = version_tuple = (0, 0, 'post31')
+
+__commit_id__ = commit_id = 'gcf17794dd'

slack_objects-0.0.post31/src/slack_objects/api_caller.py

@@ -0,0 +1,42 @@
+import time
+from typing import Any, Optional
+
+from slack_sdk.errors import SlackApiError
+
+from .config import SlackObjectsConfig, RateTier
+from .rate_limits import DEFAULT_RATE_POLICY, RateLimitPolicy
+
+
+class SlackApiCaller:
+    """
+    Wrapper around Slack SDK client to handle rate limiting and API calls.
+
+    Example: self.api.call(self.client, "users.lookupByEmail", email=email)
+    """
+    def __init__(self, cfg: SlackObjectsConfig, policy: RateLimitPolicy = DEFAULT_RATE_POLICY):
+        self.cfg = cfg
+        self.policy = policy
+
+    def call(self, client, method: str, *, rate_tier: Optional[RateTier] = None, use_json: bool = False, **kwargs) -> dict:
+        tier = rate_tier or self.policy.tier_for(method) or self.cfg.default_rate_tier
+
+        try:
+            if use_json:
+                resp = client.api_call(method, json=kwargs)
+            else:
+                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))
+                time.sleep(retry_after)
+                return self.call(client, method, rate_tier=tier, **kwargs)
+
+            raise

slack_objects-0.0.post31/src/slack_objects/base.py

@@ -0,0 +1,30 @@
+import logging
+from dataclasses import dataclass, field
+from typing import Optional, Any
+from slack_sdk import WebClient
+
+from .api_caller import SlackApiCaller
+from .config import SlackObjectsConfig
+
+
+@dataclass
+class SlackObjectBase:
+    """
+    Base class that all object helpers inherit from.
+
+    Holds shared context so every object doesn't need to reinvent plumbing (i.e., don't need to pass cfg, client, logger, and the apicaller).
+    Logging is optional; a default package logger will be used if none is provided.
+    """
+    cfg: SlackObjectsConfig
+    client: WebClient
+    api: SlackApiCaller
+    logger: logging.Logger = field(default_factory=lambda: logging.getLogger("slack-objects"))  # logger is guaranteed to exist via default_factory
+
+    def __post_init__(self) -> None:
+        # Required dependencies check
+        if self.cfg is None:
+            raise ValueError("cfg is required")
+        if self.client is None:
+            raise ValueError("client is required")
+        if self.api is None:
+            raise ValueError("api is required")

slack_objects-0.0.post31/src/slack_objects/client.py

@@ -0,0 +1,50 @@
+from slack_sdk import WebClient
+import logging
+from typing import Optional
+
+from .config import SlackObjectsConfig
+from .api_caller import SlackApiCaller
+from .users import Users
+from .messages import Messages
+from .conversations import Conversations
+from .files import Files
+from .workspaces import Workspaces
+from .idp_groups import IDP_groups
+
+
+class SlackObjectsClient:
+    """
+    Central factory / context object.
+    Owns config, Slack client, and rate-limited API caller.
+    """
+
+    def __init__(self, cfg: SlackObjectsConfig, logger: logging.Logger | None = None):
+        self.cfg = cfg
+        self.logger = logger or logging.getLogger("slack-objects")
+
+        # Prefer bot token for general Web API calls; fall back to user token.
+        web_token = cfg.bot_token or cfg.user_token
+        if not web_token:
+            raise ValueError("SlackObjectsClient requires cfg.bot_token or cfg.user_token.")
+
+        self.web_client = WebClient(token=web_token)
+        self.api = SlackApiCaller(cfg)
+
+    def users(self, user_id: Optional[str] = None) -> Users:
+        base = Users(cfg=self.cfg, client=self.web_client, api=self.api, logger=self.logger)
+        return base if user_id is None else base.with_user(user_id)
+
+    def conversations(self) -> Conversations:
+        return Conversations(cfg=self.cfg, client=self.web_client, api=self.api, logger=self.logger)
+
+    def files(self) -> Files:
+        return Files(cfg=self.cfg, client=self.web_client, api=self.api, logger=self.logger)
+
+    def messages(self) -> Messages:
+        return Messages(cfg=self.cfg, client=self.web_client, api=self.api, logger=self.logger)
+
+    def workspaces(self) -> Workspaces:
+        return Workspaces(cfg=self.cfg, client=self.web_client, api=self.api, logger=self.logger)
+
+    def idp_groups(self) -> IDP_groups:
+        return IDP_groups(cfg=self.cfg, client=self.web_client, api=self.api, logger=self.logger)

slack_objects-0.0.post31/src/slack_objects/config.py

@@ -0,0 +1,29 @@
+from enum import Enum
+from dataclasses import dataclass
+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] = None
+	user_token: Optional[str] = None
+	scim_token: Optional[str] = None
+
+	default_rate_tier: RateTier = RateTier.TIER_2