msteamsnotifiers: Decorators for automatically notifying an MS Teams channel of events
======================================================================================
`msteamsnotifiers` makes it easy to automatically send notifications to a channel in MS Teams from Python.
With the [upcoming retirement of Office 365 Connectors](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/),
this library has been updated to use Workflows. Follow the instructions in [this simple, short video](https://www.youtube.com/watch?v=jHTU_jUnswY) to set up the Workflow for your Teams channel. You can then get the webhook URL from the "When a Teams webhook request is received" step of the workflow (it's the auto-generated HTTP POST URL field, which has a handy 'copy' button next to it).
## Installation
Install with `pip`:
```
pip install msteamsnotifiers
```
## Usage
All the functions provided in `msteamsnotifiers` can take the webhook URL as an argument. If not specified, the value in `msteamsnotifiers.default_webhook_url` will be used. This allows you to set this once and then not have to pass it to the other functions each time they are used:
```python
import msteamsnotifiers
msteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'
```
### Posting simple messages to a channel
This is the simplest way of posting very simple messages to a channel in MS Teams.
```python
import msteamsnotifiers
msteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'
msteamsnotifiers.post_simple_teams_message('Hello channel!')
msteamsnotifiers.post_simple_teams_message('[Markdown formatting](https://www.markdownguide.org/) is supported.')
msteamsnotifiers.post_simple_teams_message('This was sent using [msteamsnotifiers](https://pypi.org/project/msteamsnotifiers/)')
```
### Notifying a channel of an exception
`@notify_exceptions` is a decorator that will catch any exceptions in the decorated function and send a specially formatted message with details about the exception to a channel.
```python
import msteamsnotifiers
from msteamsnotifiers import notify_exceptions
msteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'
@notify_exceptions()
def fn_with_potential_exception(a, b):
return a + b
# This function call completes successfully, so the channel will not be notified
sum1 = fn_with_potential_exception(1, 2)
# This function call will generate an exception, resulting in the channel being notified
sum2 = fn_with_potential_exception('a', True)
```
The format of the channel notification can be specified using the `template` decorator argument. If no template is specified, the default template is `msteamsnotifiers.default_exception_template`, which includes the full traceback:
```python
default_exception_template = """
*{timestamp}*
Exception caught in **{funcname}()**, File **"{filename}"**
**{message}**
<br>
Node: {machine_name} ({ip_address})
<br>
```{where}```
args: {args}
kwargs: {kwargs}
Full traceback:
```{traceback}```
"""
```
This package variable can be modified similarly to the `default_webhook_url` parameter.
The `friendly_tracebacks` module is used to format the included traceback to make it easier to read.
### Notifying a channel of a function's completion
`@notify_complete` is a decorator that will send a message to a channel upon successful completion of the decorated function.
```python
import msteamsnotifiers
from msteamsnotifiers import notify_complete
msteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'
import time
@notify_complete()
def long_running_function(a, b):
print('Thinking... thinking... thinking...')
time.sleep(3600)
print(f"Aha! The answer is {a+b}!")
return a + b
# The channel will be notified upon completion of this function call
sum1 = long_running_function(1, 2)
```
The format of this message can be specified using the `template` decorator argument. If no template is specified, the default template is `msteamsnotifiers.default_completion_template`:
```python
default_completion_template = """
*{timestamp}*
Function completed: **{funcname}()** in file **"{filename}"**
Node: {machine_name} ({ip_address})
args: {args}
kwargs: {kwargs}
"""
```
Releases
--------
### 0.2: 2024-07-18
- Update to support the new data schema required by the Workflows app.
- [Office 365 Connectors are going away](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/)
- This version won't be compatible with O365 Connector webhooks you've previously set up. According to the link directly above, you won't be able to create new Connector webhooks after August 15th, 2024. Existing connector webhooks will stop working on October 1st, 2024.
- Removed dependency on `pymsteams` (an excellent library, *RIP*)
### 0.1: 2021-10-02
- Initial release
Raw data
{
"_id": null,
"home_page": "https://github.com/joshburnett/msteamsnotifiers",
"name": "msteamsnotifiers",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Microsoft Teams msteams channel notify message post",
"author": "Josh Burnett",
"author_email": "github@burnettsonline.org",
"download_url": "https://files.pythonhosted.org/packages/ac/f1/14d97d7321da3c0fb7a0dcd9e9cc485d31d8bbab8c2f412f4cc1dec4ae37/msteamsnotifiers-0.2.0.tar.gz",
"platform": null,
"description": "msteamsnotifiers: Decorators for automatically notifying an MS Teams channel of events\r\n======================================================================================\r\n\r\n`msteamsnotifiers` makes it easy to automatically send notifications to a channel in MS Teams from Python.\r\n\r\nWith the [upcoming retirement of Office 365 Connectors](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/), \r\nthis library has been updated to use Workflows. Follow the instructions in [this simple, short video](https://www.youtube.com/watch?v=jHTU_jUnswY) to set up the Workflow for your Teams channel. You can then get the webhook URL from the \"When a Teams webhook request is received\" step of the workflow (it's the auto-generated HTTP POST URL field, which has a handy 'copy' button next to it).\r\n\r\n## Installation\r\n\r\nInstall with `pip`:\r\n\r\n```\r\npip install msteamsnotifiers\r\n```\r\n\r\n## Usage\r\n\r\nAll the functions provided in `msteamsnotifiers` can take the webhook URL as an argument. If not specified, the value in `msteamsnotifiers.default_webhook_url` will be used. This allows you to set this once and then not have to pass it to the other functions each time they are used:\r\n\r\n```python\r\nimport msteamsnotifiers\r\n\r\nmsteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'\r\n```\r\n\r\n### Posting simple messages to a channel\r\n\r\nThis is the simplest way of posting very simple messages to a channel in MS Teams.\r\n\r\n```python\r\nimport msteamsnotifiers\r\n\r\nmsteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'\r\n\r\nmsteamsnotifiers.post_simple_teams_message('Hello channel!')\r\nmsteamsnotifiers.post_simple_teams_message('[Markdown formatting](https://www.markdownguide.org/) is supported.')\r\nmsteamsnotifiers.post_simple_teams_message('This was sent using [msteamsnotifiers](https://pypi.org/project/msteamsnotifiers/)')\r\n\r\n```\r\n\r\n\r\n### Notifying a channel of an exception\r\n\r\n`@notify_exceptions` is a decorator that will catch any exceptions in the decorated function and send a specially formatted message with details about the exception to a channel.\r\n\r\n```python\r\nimport msteamsnotifiers\r\nfrom msteamsnotifiers import notify_exceptions\r\n\r\nmsteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'\r\n\r\n@notify_exceptions()\r\ndef fn_with_potential_exception(a, b):\r\n return a + b\r\n\r\n# This function call completes successfully, so the channel will not be notified\r\nsum1 = fn_with_potential_exception(1, 2)\r\n\r\n# This function call will generate an exception, resulting in the channel being notified\r\nsum2 = fn_with_potential_exception('a', True)\r\n```\r\n\r\nThe format of the channel notification can be specified using the `template` decorator argument. If no template is specified, the default template is `msteamsnotifiers.default_exception_template`, which includes the full traceback:\r\n\r\n```python\r\ndefault_exception_template = \"\"\"\r\n*{timestamp}* \r\nException caught in **{funcname}()**, File **\"{filename}\"** \r\n**{message}** \r\n<br>\r\nNode: {machine_name} ({ip_address})\r\n<br>\r\n\r\n```{where}```\r\n\r\nargs: {args} \r\nkwargs: {kwargs}\r\n\r\nFull traceback: \r\n```{traceback}```\r\n\"\"\"\r\n```\r\n\r\nThis package variable can be modified similarly to the `default_webhook_url` parameter.\r\n\r\nThe `friendly_tracebacks` module is used to format the included traceback to make it easier to read. \r\n\r\n### Notifying a channel of a function's completion\r\n\r\n`@notify_complete` is a decorator that will send a message to a channel upon successful completion of the decorated function.\r\n\r\n```python\r\nimport msteamsnotifiers\r\nfrom msteamsnotifiers import notify_complete\r\n\r\nmsteamsnotifiers.default_webhook_url = '<your Microsoft webhook URL>'\r\n\r\nimport time\r\n\r\n@notify_complete()\r\ndef long_running_function(a, b):\r\n print('Thinking... thinking... thinking...')\r\n time.sleep(3600)\r\n print(f\"Aha! The answer is {a+b}!\")\r\n return a + b\r\n\r\n# The channel will be notified upon completion of this function call\r\nsum1 = long_running_function(1, 2)\r\n```\r\n\r\nThe format of this message can be specified using the `template` decorator argument. If no template is specified, the default template is `msteamsnotifiers.default_completion_template`:\r\n\r\n```python\r\ndefault_completion_template = \"\"\"\r\n*{timestamp}* \r\nFunction completed: **{funcname}()** in file **\"{filename}\"** \r\nNode: {machine_name} ({ip_address}) \r\nargs: {args} \r\nkwargs: {kwargs}\r\n\"\"\"\r\n```\r\n\r\n\r\nReleases\r\n--------\r\n### 0.2: 2024-07-18\r\n\r\n- Update to support the new data schema required by the Workflows app.\r\n - [Office 365 Connectors are going away](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/)\r\n - This version won't be compatible with O365 Connector webhooks you've previously set up. According to the link directly above, you won't be able to create new Connector webhooks after August 15th, 2024. Existing connector webhooks will stop working on October 1st, 2024. \r\n- Removed dependency on `pymsteams` (an excellent library, *RIP*)\r\n\r\n### 0.1: 2021-10-02\r\n\r\n- Initial release\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Decorators for automatically notifying an MS Teams channel of events",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/joshburnett/msteamsnotifiers"
},
"split_keywords": [
"microsoft",
"teams",
"msteams",
"channel",
"notify",
"message",
"post"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0fdb4a6af38bf9a67b6ed2e7976e5582e163d687c8d0c7f371401470333cc013",
"md5": "598faa01fde884cbd68abfdc78ebed76",
"sha256": "b371c8cbe9994b8a781d55dcde792ed64c002dcd2f6441e1909396fa2dedb2bc"
},
"downloads": -1,
"filename": "msteamsnotifiers-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "598faa01fde884cbd68abfdc78ebed76",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5918,
"upload_time": "2024-08-21T19:30:08",
"upload_time_iso_8601": "2024-08-21T19:30:08.673053Z",
"url": "https://files.pythonhosted.org/packages/0f/db/4a6af38bf9a67b6ed2e7976e5582e163d687c8d0c7f371401470333cc013/msteamsnotifiers-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "acf114d97d7321da3c0fb7a0dcd9e9cc485d31d8bbab8c2f412f4cc1dec4ae37",
"md5": "cfd8bcf43a7300d0259092186633b4cb",
"sha256": "abcf674acde3750c8325af52ced51d4939654a828f069efe49c35b9f047cdf6f"
},
"downloads": -1,
"filename": "msteamsnotifiers-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "cfd8bcf43a7300d0259092186633b4cb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5769,
"upload_time": "2024-08-21T19:30:09",
"upload_time_iso_8601": "2024-08-21T19:30:09.944891Z",
"url": "https://files.pythonhosted.org/packages/ac/f1/14d97d7321da3c0fb7a0dcd9e9cc485d31d8bbab8c2f412f4cc1dec4ae37/msteamsnotifiers-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-21 19:30:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "joshburnett",
"github_project": "msteamsnotifiers",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "msteamsnotifiers"
}
JSON
