lupaxa-slackit 0.1.0__tar.gz

lupaxa_slackit-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# OS
+.DS_Store
+
+# Cursor
+.superpowers/
+cursor-docs
+
+# Make
+.makefiles/
+
+# MkDocs
+site/
+
+# Python
+.venv/
+.coverage
+__pycache__/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+dist/
+build/
+*.egg-info/

lupaxa_slackit-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) The Lupaxa Project
+
+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.

lupaxa_slackit-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.5
+Name: lupaxa-slackit
+Version: 0.1.0
+Summary: Send Slack messages through an incoming webhook.
+Project-URL: Homepage, https://slackit.thelupaxaproject.org/
+Project-URL: Documentation, https://slackit.thelupaxaproject.org/
+Project-URL: Repository, https://github.com/lupaxa-notifications-toolbox/slackit
+Project-URL: Issues, https://github.com/lupaxa-notifications-toolbox/slackit/issues
+Author: The Lupaxa Project
+License: MIT License
+        
+        Copyright (c) The Lupaxa Project
+        
+        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.
+License-File: LICENCE
+Keywords: cli,notifications,slack,webhook
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: pyyaml>=6
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: bump-my-version>=1.2.0; extra == 'dev'
+Requires-Dist: hatch>=1.12.0; extra == 'dev'
+Requires-Dist: mkdocs-material==9.7.7; extra == 'dev'
+Requires-Dist: mkdocs==1.6.1; extra == 'dev'
+Requires-Dist: mypy>=1.12.0; extra == 'dev'
+Requires-Dist: pip-audit>=2.7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable -->
+<p align="center">
+  <a href="https://github.com/lupaxa-notifications-toolbox">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/notifications-toolbox/readme-logo.png" alt="Project Logo" width="256"/><br/>
+  </a>
+</p>
+<h3 align="center">
+  The Lupaxa Notifications Toolbox<br />
+  Part of The Lupaxa Project
+</h3>
+
+<br />
+
+# lupaxa-slackit
+
+Send Slack messages through an incoming webhook.
+
+## Features
+
+- Post message text, one attachment, or Block Kit blocks
+- Set a username, channel, and icon emoji on each client
+- Keep several webhook profiles in `$HOME/.slackit.yml` and select one with `--profile`
+- Override any profile field with a CLI flag
+- Turn escaped `\n` sequences in message text into real line breaks
+- Reject webhook URLs that do not start with `https://hooks.slack.com/services/`
+- Reject webhook URLs that answer `HEAD` with a redirect
+- Use the `Slackit` library class or the `slackit` command
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install lupaxa-slackit
+```
+
+### From source (development mode)
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.13+. Runtime dependencies: `requests` and `PyYAML`.
+
+## Library quick start
+
+```python
+from lupaxa.slackit import Slackit, load_profile
+
+profile = load_profile("testing")
+client = Slackit(
+    profile.webhook_url,
+    username=profile.username,
+    channel=profile.channel,
+    icon_emoji=profile.icon_emoji,
+)
+client.send_message("Hello from a profile")
+
+client = Slackit(
+    "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
+    username="PyBot",
+    channel="#testing",
+    icon_emoji=":robot_face:",
+)
+client.send_message("Hello, Slack!")
+client.send_attachment('{"text": "Optional text inside the attachment"}')
+client.send_block('[{"type": "section", "text": {"type": "mrkdwn", "text": "Hello"}}]')
+```
+
+## CLI quick start
+
+```bash
+slackit --help
+slackit --webhook "$SLACK_WEBHOOK_URL" --text "Hello, Slack!"
+slackit --profile testing --text "Hello, Slack!"
+slackit -p alerts --config "$HOME/work/slackit.yml" --text "Disk full"
+```
+
+You can also run the CLI as a module:
+
+```bash
+python -m lupaxa.slackit --help
+python -m lupaxa.slackit --version
+```
+
+## Config
+
+Profiles live in one YAML file. The default path is `$HOME/.slackit.yml`.
+Pass `--config` when the file lives somewhere else. `--config` requires
+`--profile`. CLI flags override the selected profile.
+
+```yaml
+profiles:
+  testing:
+    webhook_url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX
+    username: PyBot
+    channel: "#testing"
+    icon_emoji: ":robot_face:"
+    timeout: 15
+  alerts:
+    webhook_url: https://hooks.slack.com/services/T00000000/B00000000/YYYYYYYY
+    channel: "#alerts"
+```
+
+Each profile may set `webhook_url`, `username`, `channel`, `icon_emoji`, and
+`timeout`. `--webhook` is required when you do not pass `--profile`.
+
+## Options
+
+- `--webhook`, `-w`: Slack incoming webhook URL; required when `--profile` is omitted
+- `--profile`, `-p`: profile name in the config file
+- `--config`: config file path; default `$HOME/.slackit.yml`
+- `--text`, `-t`: message text
+- `--attachment`, `-a`: one attachment as a JSON object
+- `--blocks`, `-b`: Block Kit payload as JSON
+- `--validate`: send a validation message to channel `general`
+- `--username`, `-u`: display name
+- `--channel`, `-c`: channel override
+- `--icon-emoji`, `-i`: icon emoji
+- `--timeout`, `-T`: request timeout in seconds; default `10`
+- `--version`: print the package version
+
+`--text`, `--attachment`, `--blocks`, and `--validate` are mutually exclusive.
+One of them is required. CLI flags override the selected profile.
+
+## Documentation
+
+Online documentation:
+
+[Documentation](https://slackit.thelupaxaproject.org/)
+
+Source repository:
+
+[GitHub](https://github.com/lupaxa-notifications-toolbox/slackit)
+
+### Serve docs locally
+
+From a clone of the repository:
+
+```bash
+make mkdocs-serve
+```
+
+Then open the local URL printed by MkDocs in your browser.
+
+## Development
+
+Clone the repository and install with Make:
+
+```bash
+make init                # first-time makefile-skills checkout
+make python-install-dev  # editable install with [dev]
+make python-check        # lint, type-check, and test
+```
+
+<a href="https://github.com/the-lupaxa-project">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
+</a>

lupaxa_slackit-0.1.0/README-PYPI.md

@@ -0,0 +1,158 @@
+<!-- markdownlint-disable -->
+<p align="center">
+  <a href="https://github.com/lupaxa-notifications-toolbox">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/notifications-toolbox/readme-logo.png" alt="Project Logo" width="256"/><br/>
+  </a>
+</p>
+<h3 align="center">
+  The Lupaxa Notifications Toolbox<br />
+  Part of The Lupaxa Project
+</h3>
+
+<br />
+
+# lupaxa-slackit
+
+Send Slack messages through an incoming webhook.
+
+## Features
+
+- Post message text, one attachment, or Block Kit blocks
+- Set a username, channel, and icon emoji on each client
+- Keep several webhook profiles in `$HOME/.slackit.yml` and select one with `--profile`
+- Override any profile field with a CLI flag
+- Turn escaped `\n` sequences in message text into real line breaks
+- Reject webhook URLs that do not start with `https://hooks.slack.com/services/`
+- Reject webhook URLs that answer `HEAD` with a redirect
+- Use the `Slackit` library class or the `slackit` command
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install lupaxa-slackit
+```
+
+### From source (development mode)
+
+```bash
+pip install -e ".[dev]"
+```
+
+Requires Python 3.13+. Runtime dependencies: `requests` and `PyYAML`.
+
+## Library quick start
+
+```python
+from lupaxa.slackit import Slackit, load_profile
+
+profile = load_profile("testing")
+client = Slackit(
+    profile.webhook_url,
+    username=profile.username,
+    channel=profile.channel,
+    icon_emoji=profile.icon_emoji,
+)
+client.send_message("Hello from a profile")
+
+client = Slackit(
+    "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX",
+    username="PyBot",
+    channel="#testing",
+    icon_emoji=":robot_face:",
+)
+client.send_message("Hello, Slack!")
+client.send_attachment('{"text": "Optional text inside the attachment"}')
+client.send_block('[{"type": "section", "text": {"type": "mrkdwn", "text": "Hello"}}]')
+```
+
+## CLI quick start
+
+```bash
+slackit --help
+slackit --webhook "$SLACK_WEBHOOK_URL" --text "Hello, Slack!"
+slackit --profile testing --text "Hello, Slack!"
+slackit -p alerts --config "$HOME/work/slackit.yml" --text "Disk full"
+```
+
+You can also run the CLI as a module:
+
+```bash
+python -m lupaxa.slackit --help
+python -m lupaxa.slackit --version
+```
+
+## Config
+
+Profiles live in one YAML file. The default path is `$HOME/.slackit.yml`.
+Pass `--config` when the file lives somewhere else. `--config` requires
+`--profile`. CLI flags override the selected profile.
+
+```yaml
+profiles:
+  testing:
+    webhook_url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX
+    username: PyBot
+    channel: "#testing"
+    icon_emoji: ":robot_face:"
+    timeout: 15
+  alerts:
+    webhook_url: https://hooks.slack.com/services/T00000000/B00000000/YYYYYYYY
+    channel: "#alerts"
+```
+
+Each profile may set `webhook_url`, `username`, `channel`, `icon_emoji`, and
+`timeout`. `--webhook` is required when you do not pass `--profile`.
+
+## Options
+
+- `--webhook`, `-w`: Slack incoming webhook URL; required when `--profile` is omitted
+- `--profile`, `-p`: profile name in the config file
+- `--config`: config file path; default `$HOME/.slackit.yml`
+- `--text`, `-t`: message text
+- `--attachment`, `-a`: one attachment as a JSON object
+- `--blocks`, `-b`: Block Kit payload as JSON
+- `--validate`: send a validation message to channel `general`
+- `--username`, `-u`: display name
+- `--channel`, `-c`: channel override
+- `--icon-emoji`, `-i`: icon emoji
+- `--timeout`, `-T`: request timeout in seconds; default `10`
+- `--version`: print the package version
+
+`--text`, `--attachment`, `--blocks`, and `--validate` are mutually exclusive.
+One of them is required. CLI flags override the selected profile.
+
+## Documentation
+
+Online documentation:
+
+[Documentation](https://slackit.thelupaxaproject.org/)
+
+Source repository:
+
+[GitHub](https://github.com/lupaxa-notifications-toolbox/slackit)
+
+### Serve docs locally
+
+From a clone of the repository:
+
+```bash
+make mkdocs-serve
+```
+
+Then open the local URL printed by MkDocs in your browser.
+
+## Development
+
+Clone the repository and install with Make:
+
+```bash
+make init                # first-time makefile-skills checkout
+make python-install-dev  # editable install with [dev]
+make python-check        # lint, type-check, and test
+```
+
+<a href="https://github.com/the-lupaxa-project">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
+</a>

lupaxa_slackit-0.1.0/README.md

@@ -0,0 +1,84 @@
+<p align="center">
+  <a href="https://github.com/lupaxa-notifications-toolbox">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/notifications-toolbox/readme-logo.png" alt="Notifications Toolbox" />
+  </a>
+</p>
+
+<h1 align="center">slackit</h1>
+
+Send Slack messages through an incoming webhook.
+
+<p align="center">
+  <a href="https://slackit.thelupaxaproject.org/">Documentation</a>
+  ·
+  <a href="https://github.com/lupaxa-notifications-toolbox/slackit">GitHub</a>
+</p>
+
+## Install
+
+```bash
+pip install lupaxa-slackit
+slackit --help
+```
+
+## CLI
+
+```bash
+slackit --webhook "$SLACK_WEBHOOK_URL" --text "Hello, Slack!"
+slackit --profile testing --text "Hello, Slack!"
+slackit -p alerts --config "$HOME/work/slackit.yml" --text "Disk full"
+python -m lupaxa.slackit --version
+```
+
+The webhook URL must start with `https://hooks.slack.com/services/`.
+`--text`, `--attachment`, `--blocks`, and `--validate` are mutually exclusive.
+Flags override the same fields from the selected profile.
+
+## Config
+
+Profiles live in `$HOME/.slackit.yml`. Pass `--config` to use another file.
+`--config` requires `--profile`.
+
+```yaml
+profiles:
+  testing:
+    webhook_url: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX
+    username: PyBot
+    channel: "#testing"
+    icon_emoji: ":robot_face:"
+    timeout: 15
+  alerts:
+    webhook_url: https://hooks.slack.com/services/T00000000/B00000000/YYYYYYYY
+    channel: "#alerts"
+```
+
+Each profile may set `webhook_url`, `username`, `channel`, `icon_emoji`, and
+`timeout`.
+
+## Library
+
+```python
+from lupaxa.slackit import Slackit, load_profile
+
+profile = load_profile("testing")
+client = Slackit(
+    profile.webhook_url,
+    username=profile.username,
+    channel=profile.channel,
+    icon_emoji=profile.icon_emoji,
+)
+client.send_message("Hello, Slack!")
+```
+
+## Development
+
+```bash
+make init
+make python-install-dev
+make python-check
+make mkdocs-serve
+```
+
+<a href="https://github.com/the-lupaxa-project">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
+</a>

lupaxa_slackit-0.1.0/docs/README.md

@@ -0,0 +1,23 @@
+<p align="center">
+    <a href="https://github.com/lupaxa-notifications-toolbox">
+        <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/organisations/notifications-toolbox/readme-logo.png" alt="Organisation Logo" />
+    </a>
+</p>
+
+<h1 align="center">Core Documentation</h1>
+
+The following documents define the standards that apply across **The Lupaxa Project**:
+
+| Document                              | Purpose                                                           |
+| :------------------------------------ | :---------------------------------------------------------------- |
+| [Code of Conduct](CODE_OF_CONDUCT.md) | Expected behaviour and reporting procedures.                      |
+| [How to Contribute](CONTRIBUTING.md)  | Development workflow, coding standards, and contribution process. |
+| [Governance](GOVERNANCE.md)           | Project governance, roles, and decision-making.                   |
+| [Maintainers](MAINTAINERS.md)         | Maintainer responsibilities and expectations.                     |
+| [Projects Overview](PROJECTS.md)      | Overview of organisations, repositories, and project structure.   |
+| [Security Policy](SECURITY.md)        | Responsible disclosure and secure development practices.          |
+| [Support Guide](SUPPORT.md)           | How to obtain help and support.                                   |
+
+<a href="https://github.com/the-lupaxa-project">
+    <img src="https://raw.githubusercontent.com/the-lupaxa-project/brand-assets/master/logos/components/footer-for-child-orgs.svg" alt="The Lupaxa Project Footer" width="100%" />
+</a>

lupaxa_slackit-0.1.0/pyproject.toml

@@ -0,0 +1,122 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lupaxa-slackit"
+dynamic = ["version"]
+description = "Send Slack messages through an incoming webhook."
+readme = "README-PYPI.md"
+license = { file = "LICENCE" }
+requires-python = ">=3.13"
+
+authors = [
+  { name = "The Lupaxa Project" }
+]
+
+keywords = ["slack", "webhook", "notifications", "cli"]
+
+dependencies = [
+  "requests>=2.32",
+  "PyYAML>=6",
+]
+
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Communications :: Chat",
+  "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://slackit.thelupaxaproject.org/"
+Documentation = "https://slackit.thelupaxaproject.org/"
+Repository = "https://github.com/lupaxa-notifications-toolbox/slackit"
+Issues = "https://github.com/lupaxa-notifications-toolbox/slackit/issues"
+
+[project.scripts]
+slackit = "lupaxa.slackit.cli:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.6.0",
+  "mypy>=1.12.0",
+  "hatch>=1.12.0",
+  "bump-my-version>=1.2.0",
+  "pip-audit>=2.7.0",
+  "mkdocs==1.6.1",
+  "mkdocs-material==9.7.7",
+]
+test = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+]
+
+[tool.hatch.version]
+path = "src/lupaxa/slackit/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/**",
+  "README.md",
+  "README-PYPI.md",
+  "LICENCE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lupaxa"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "S", "UP", "SIM", "C4", "ISC", "D", "ANN", "PT"]
+ignore = [
+  "D200", "D201", "D202", "D203", "D204", "D205", "D206", "D207", "D208", "D209", "D210", "D211", "D212",
+  "ISC001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "S104", "S105", "S106", "D", "ANN001", "ANN201"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src", "tests"]
+mypy_path = "src"
+explicit_package_bases = true
+namespace_packages = true
+warn_unused_configs = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+follow_imports = "normal"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "-ra -q --disable-warnings --cov=lupaxa.slackit --cov-report=term-missing"
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["lupaxa.slackit"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true

lupaxa_slackit-0.1.0/src/lupaxa/slackit/__init__.py

@@ -0,0 +1,19 @@
+"""lupaxa.slackit — send Slack messages through an incoming webhook."""
+
+from __future__ import annotations
+
+from .client import DEFAULT_TIMEOUT, WEBHOOK_PREFIX, Slackit
+from .config import ConfigError, Profile, default_config_path, load_profile
+from .version import __version__, get_version
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "WEBHOOK_PREFIX",
+    "ConfigError",
+    "Profile",
+    "Slackit",
+    "__version__",
+    "default_config_path",
+    "get_version",
+    "load_profile",
+]

lupaxa_slackit-0.1.0/src/lupaxa/slackit/__main__.py

@@ -0,0 +1,8 @@
+"""Allow ``python -m lupaxa.slackit`` to run the CLI."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lupaxa_slackit-0.1.0/src/lupaxa/slackit/cli.py

@@ -0,0 +1,143 @@
+"""Command-line interface for Slackit."""
+
+from __future__ import annotations
+
+import argparse
+import math
+import os
+import sys
+from pathlib import Path
+
+import requests
+
+from .client import DEFAULT_TIMEOUT, Slackit
+from .config import ConfigError, resolve_settings
+from .version import get_version
+
+
+def _positive_timeout(value: str) -> float:
+    try:
+        timeout = float(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("timeout must be a number") from exc
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise argparse.ArgumentTypeError("timeout must be greater than 0")
+    return timeout
+
+
+def _exit_code(exc: SystemExit) -> int:
+    code = exc.code
+    if code is None:
+        return 0
+    return code if isinstance(code, int) else 1
+
+
+def _program_name(argv0: str) -> str:
+    name = os.path.basename(argv0)
+    return "slackit" if name == "__main__.py" else name
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the ``slackit`` argument parser."""
+    parser = argparse.ArgumentParser(
+        description="Send a Slack message through an incoming webhook.",
+    )
+    parser.add_argument(
+        "-w",
+        "--webhook",
+        default=None,
+        metavar="URL",
+        help="Slack incoming webhook URL (overrides the profile)",
+    )
+    parser.add_argument(
+        "-p",
+        "--profile",
+        default=None,
+        metavar="NAME",
+        help="Profile name in the config file",
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        metavar="PATH",
+        help="Config file (default: ~/.slackit.yml)",
+    )
+    parser.add_argument("-u", "--username", default=None, help="Display name")
+    parser.add_argument(
+        "-c",
+        "--channel",
+        default=None,
+        help="Channel, such as #testing",
+    )
+    parser.add_argument(
+        "-i",
+        "--icon-emoji",
+        dest="icon_emoji",
+        default=None,
+        help="Icon emoji, such as :robot_face:",
+    )
+    parser.add_argument(
+        "-T",
+        "--timeout",
+        type=_positive_timeout,
+        default=None,
+        metavar="SECONDS",
+        help=f"Request timeout in seconds (default: {DEFAULT_TIMEOUT:g})",
+    )
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("-t", "--text", help="Message text")
+    mode.add_argument("-a", "--attachment", help="Attachment JSON object")
+    mode.add_argument("-b", "--blocks", help="Block Kit JSON")
+    mode.add_argument(
+        "--validate",
+        action="store_true",
+        help="Send a validation message to #general",
+    )
+    parser.add_argument("--version", action="version", version=get_version())
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return a process exit code."""
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        return _exit_code(exc)
+
+    config_path = Path(args.config).expanduser() if args.config else None
+    try:
+        settings = resolve_settings(
+            profile_name=args.profile,
+            config_path=config_path,
+            webhook_url=args.webhook,
+            username=args.username,
+            channel=args.channel,
+            icon_emoji=args.icon_emoji,
+            timeout=args.timeout,
+        )
+        client = Slackit(
+            settings.webhook_url,
+            username=settings.username,
+            channel=settings.channel,
+            icon_emoji=settings.icon_emoji,
+            timeout=settings.timeout,
+        )
+        if args.validate:
+            if not client.validate():
+                print(f"{_program_name(sys.argv[0])}: invalid webhook URL", file=sys.stderr)
+                return 1
+            return 0
+        if args.text is not None:
+            client.send_message(args.text)
+        elif args.attachment is not None:
+            client.send_attachment(args.attachment)
+        elif args.blocks is not None:
+            client.send_block(args.blocks)
+    except ConfigError as exc:
+        print(f"{_program_name(sys.argv[0])}: {exc}", file=sys.stderr)
+        return 2
+    except (ValueError, requests.RequestException) as exc:
+        print(f"{_program_name(sys.argv[0])}: {exc}", file=sys.stderr)
+        return 1
+    return 0

lupaxa_slackit-0.1.0/src/lupaxa/slackit/client.py

@@ -0,0 +1,132 @@
+"""Slack incoming-webhook client."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import cast
+
+import requests
+
+DEFAULT_TIMEOUT = 10.0
+WEBHOOK_PREFIX = "https://hooks.slack.com/services/"
+_REDIRECT_STATUSES = {301, 302}
+
+type JsonValue = None | bool | int | float | str | list[JsonValue] | dict[str, JsonValue]
+
+
+class Slackit:
+    """Send messages through a Slack incoming webhook."""
+
+    def __init__(
+        self,
+        webhook_url: str,
+        *,
+        username: str | None = None,
+        channel: str | None = None,
+        icon_emoji: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        """Store webhook settings after the URL passes validation."""
+        if not webhook_url:
+            raise ValueError("Webhook URL required")
+        if not webhook_url.startswith(WEBHOOK_PREFIX):
+            raise ValueError(
+                f"Invalid webhook URL: {webhook_url} - should start with {WEBHOOK_PREFIX}"
+            )
+        self.webhook_url = webhook_url
+        self.username = username
+        self.channel = channel
+        self.icon_emoji = icon_emoji
+        self.timeout = _require_timeout(timeout)
+        if not self.valid_webhook(self.webhook_url):
+            raise ValueError(
+                f"Invalid webhook URL: {self.webhook_url} - please check your configuration"
+            )
+
+    def valid_webhook(self, url: str) -> bool:
+        """Return whether ``url`` answers without a redirect."""
+        try:
+            response = requests.head(
+                url,
+                allow_redirects=False,
+                timeout=self.timeout,
+            )
+        except requests.RequestException:
+            return False
+        return response.status_code not in _REDIRECT_STATUSES
+
+    def send_message(self, text: str) -> bool:
+        """Post ``text``, turning escaped newlines into real line breaks."""
+        return self.send_payload({"text": text.replace("\\n", "\n")})
+
+    def send(self, text: str) -> bool:
+        """Post ``text``. Alias of ``send_message``."""
+        return self.send_message(text)
+
+    def send_attachment(self, attachment: str) -> bool:
+        """Post one attachment encoded as a JSON object string."""
+        return self.send_payload({"attachments": [self.convert_to_json(attachment)]})
+
+    def send_block(self, block: str) -> bool:
+        """Post Block Kit blocks encoded as a JSON string."""
+        return self.send_payload({"blocks": self.convert_to_json(block)})
+
+    def convert_to_json(self, json_string: str) -> JsonValue:
+        """Parse ``json_string`` or raise ``ValueError``."""
+        try:
+            parsed = json.loads(json_string)
+        except json.JSONDecodeError as exc:
+            raise ValueError("Invalid json") from exc
+        return cast(JsonValue, parsed)
+
+    def send_payload(self, payload: dict[str, JsonValue]) -> bool:
+        """POST ``payload`` as JSON, filling username, channel, and icon."""
+        body = _with_defaults(payload, self.icon_emoji, self.username, self.channel)
+        response = requests.post(
+            self.webhook_url,
+            headers={"Content-Type": "application/json"},
+            json=body,
+            timeout=self.timeout,
+            allow_redirects=False,
+        )
+        if response.status_code == 200:
+            return True
+        if response.status_code in _REDIRECT_STATUSES:
+            raise ValueError(
+                f"Invalid webhook URL: {self.webhook_url} - please check your configuration"
+            )
+        if not response.text:
+            raise ValueError(f"Unknown error for webhook URL: {self.webhook_url}")
+        raise ValueError(response.text)
+
+    def validate(self) -> bool:
+        """Send a validation message to channel ``general`` when HEAD succeeds."""
+        if not self.valid_webhook(self.webhook_url):
+            return False
+        self.channel = "general"
+        self.send_message("This is a validation message")
+        return True
+
+
+def _require_timeout(timeout: float) -> float:
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError("timeout must be greater than 0")
+    return timeout
+
+
+def _with_defaults(
+    payload: dict[str, JsonValue],
+    icon_emoji: str | None,
+    username: str | None,
+    channel: str | None,
+) -> dict[str, JsonValue]:
+    body = dict(payload)
+    for key, value in (
+        ("icon_emoji", icon_emoji),
+        ("username", username),
+        ("channel", channel),
+    ):
+        if key not in body and value is not None:
+            body[key] = value
+    return body

lupaxa_slackit-0.1.0/src/lupaxa/slackit/config.py

@@ -0,0 +1,145 @@
+"""Load Slackit profiles from a YAML config file."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from .client import DEFAULT_TIMEOUT
+
+_PROFILE_FIELDS = ("webhook_url", "username", "channel", "icon_emoji", "timeout")
+
+
+class ConfigError(ValueError):
+    """The config file or selected profile cannot be used."""
+
+
+@dataclass(frozen=True)
+class Profile:
+    """One named block of webhook settings from the config file."""
+
+    webhook_url: str | None = None
+    username: str | None = None
+    channel: str | None = None
+    icon_emoji: str | None = None
+    timeout: float | None = None
+
+
+@dataclass(frozen=True)
+class ResolvedSettings:
+    """Webhook settings after CLI flags override a profile."""
+
+    webhook_url: str
+    username: str | None
+    channel: str | None
+    icon_emoji: str | None
+    timeout: float
+
+
+def default_config_path() -> Path:
+    """Return the default config path, ``$HOME/.slackit.yml``."""
+    return Path.home() / ".slackit.yml"
+
+
+def load_profile(name: str, path: Path | None = None) -> Profile:
+    """Load ``name`` from ``path`` or from ``$HOME/.slackit.yml``."""
+    config_path = default_config_path() if path is None else path
+    if not config_path.is_file():
+        raise ConfigError(f"config file not found: {config_path}")
+    try:
+        loaded: object = yaml.safe_load(config_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"invalid config file: {config_path}") from exc
+    profiles = _profiles(loaded, config_path)
+    if name not in profiles:
+        raise ConfigError(f"profile not found: {name}")
+    raw = profiles[name]
+    if not isinstance(raw, dict):
+        raise ConfigError(f"profile {name} must be a mapping")
+    unknown = sorted(str(key) for key in raw if key not in _PROFILE_FIELDS)
+    if unknown:
+        raise ConfigError(f"unknown profile setting: {', '.join(unknown)}")
+    return Profile(
+        webhook_url=_optional_text(raw.get("webhook_url"), "webhook_url"),
+        username=_optional_text(raw.get("username"), "username"),
+        channel=_optional_text(raw.get("channel"), "channel"),
+        icon_emoji=_optional_text(raw.get("icon_emoji"), "icon_emoji"),
+        timeout=_optional_timeout(raw.get("timeout")),
+    )
+
+
+def resolve_settings(
+    *,
+    profile_name: str | None,
+    config_path: Path | None,
+    webhook_url: str | None,
+    username: str | None,
+    channel: str | None,
+    icon_emoji: str | None,
+    timeout: float | None,
+) -> ResolvedSettings:
+    """Merge CLI values over an optional profile.
+
+    A passed CLI value wins. ``timeout`` falls back to ``DEFAULT_TIMEOUT``
+    when neither the CLI nor the profile sets it.
+    """
+    if profile_name is None and config_path is not None:
+        raise ConfigError("--profile is required when --config is set")
+    profile = load_profile(profile_name, config_path) if profile_name else None
+    resolved_webhook = _pick(webhook_url, None if profile is None else profile.webhook_url)
+    if not resolved_webhook:
+        raise ConfigError("webhook URL required")
+    if timeout is not None:
+        resolved_timeout = timeout
+    elif profile is not None and profile.timeout is not None:
+        resolved_timeout = profile.timeout
+    else:
+        resolved_timeout = DEFAULT_TIMEOUT
+    return ResolvedSettings(
+        webhook_url=resolved_webhook,
+        username=_pick(username, None if profile is None else profile.username),
+        channel=_pick(channel, None if profile is None else profile.channel),
+        icon_emoji=_pick(icon_emoji, None if profile is None else profile.icon_emoji),
+        timeout=resolved_timeout,
+    )
+
+
+def _pick(cli_value: str | None, profile_value: str | None) -> str | None:
+    return cli_value if cli_value is not None else profile_value
+
+
+def _profiles(loaded: object, config_path: Path) -> dict[object, object]:
+    if not isinstance(loaded, dict):
+        raise ConfigError(f"invalid config file: {config_path}")
+    unknown = sorted(str(key) for key in loaded if key != "profiles")
+    if unknown:
+        raise ConfigError(f"unknown config setting: {', '.join(unknown)}")
+    profiles = loaded.get("profiles")
+    if not isinstance(profiles, dict) or not profiles:
+        raise ConfigError("config file must define profiles")
+    for name in profiles:
+        if not isinstance(name, str) or not name:
+            raise ConfigError("profile names must be strings")
+    return profiles
+
+
+def _optional_text(value: object, field: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value:
+        raise ConfigError(f"{field} must be a non-empty string")
+    return value
+
+
+def _optional_timeout(value: object) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ConfigError("timeout must be a number")
+    timeout = float(value)
+    if not math.isfinite(timeout) or timeout <= 0:
+        raise ConfigError("timeout must be greater than 0")
+    return timeout

lupaxa_slackit-0.1.0/src/lupaxa/slackit/version.py

@@ -0,0 +1,10 @@
+"""Version information for lupaxa.slackit."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+
+def get_version() -> str:
+    """Return the package version string."""
+    return __version__