Skip to content

Commit 6765653

Browse files
zzstoatzzzzstoatzz
authored
Migrate prefect-email to core (#12845)
1 parent dba8485 commit 6765653

File tree

17 files changed

+963
-1
lines changed

17 files changed

+963
-1
lines changed

‎docs/integrations/catalog/prefect-email.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
collectionName: prefect-email
22
author: Prefect
33
authorUrl: https://prefect.io
4-
documentation: https://prefecthq.github.io/prefect-email/
4+
documentation: prefect-email
55
iconUrl: /img/collections/email.png
66
tag: Email

‎docs/integrations/prefect-email/credentials.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
::: prefect_email.credentials

‎docs/integrations/prefect-email/index.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# prefect-email
2+
3+
<p align="center">
4+
<a href="https://pypi.python.org/pypi/prefect-email/" alt="PyPI version">
5+
<img alt="PyPI" src="https://img.shields.io/pypi/v/prefect-email?color=0052FF&labelColor=090422"></a>
6+
<a href="https://pepy.tech/badge/prefect-email/" alt="Downloads">
7+
<img src="https://img.shields.io/pypi/dm/prefect-email?color=0052FF&labelColor=090422" /></a>
8+
</p>
9+
10+
Visit the full docs [here](https://PrefectHQ.github.io/prefect-email) to see additional examples and the API reference.
11+
12+
`prefect-email` is a collection of prebuilt Prefect integrations that can be used to interact with email services.
13+
14+
## Getting Started
15+
16+
### Integrate with Prefect flows
17+
18+
`prefect-email` makes sending emails effortless, giving you peace of mind that your emails are being sent as expected.
19+
20+
First, install [prefect-email](#installation) and [save your email credentials to a block](#saving-credentials-to-block) to run the examples below!
21+
22+
```python
23+
from prefect import flow
24+
from prefect_email import EmailServerCredentials, email_send_message
25+
26+
@flow
27+
def example_email_send_message_flow(email_addresses):
28+
email_server_credentials = EmailServerCredentials.load("BLOCK-NAME-PLACEHOLDER")
29+
for email_address in email_addresses:
30+
subject = email_send_message.with_options(name=f"email {email_address}").submit(
31+
email_server_credentials=email_server_credentials,
32+
subject="Example Flow Notification using Gmail",
33+
msg="This proves email_send_message works!",
34+
email_to=email_address,
35+
)
36+
37+
example_email_send_message_flow(["EMAIL-ADDRESS-PLACEHOLDER"])
38+
```
39+
40+
Outputs:
41+
42+
```bash
43+
16:58:27.646 | INFO | prefect.engine - Created flow run 'busy-bat' for flow 'example-email-send-message-flow'
44+
16:58:29.225 | INFO | Flow run 'busy-bat' - Created task run 'email someone@gmail.com-0' for task 'email someone@gmail.com'
45+
16:58:29.229 | INFO | Flow run 'busy-bat' - Submitted task run 'email someone@gmail.com-0' for execution.
46+
16:58:31.523 | INFO | Task run 'email someone@gmail.com-0' - Finished in state Completed()
47+
16:58:31.713 | INFO | Flow run 'busy-bat' - Finished in state Completed('All states completed.')
48+
```
49+
50+
Please note, many email services, like Gmail, require an [App Password](https://support.google.com/accounts/answer/185833) to successfully send emails. If you encounter an error similar to `smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted...`, it's likely you are not using an App Password.
51+
52+
### Capture exceptions and notify by email
53+
54+
Perhaps you want an email notification with the details of the exception when your flow run fails.
55+
56+
`prefect-email` can be wrapped in an `except` statement to do just that!
57+
58+
```python
59+
from prefect import flow
60+
from prefect.context import get_run_context
61+
from prefect_email import EmailServerCredentials, email_send_message
62+
63+
def notify_exc_by_email(exc):
64+
context = get_run_context()
65+
flow_run_name = context.flow_run.name
66+
email_server_credentials = EmailServerCredentials.load("email-server-credentials")
67+
email_send_message(
68+
email_server_credentials=email_server_credentials,
69+
subject=f"Flow run {flow_run_name!r} failed",
70+
msg=f"Flow run {flow_run_name!r} failed due to {exc}.",
71+
email_to=email_server_credentials.username,
72+
)
73+
74+
@flow
75+
def example_flow():
76+
try:
77+
1 / 0
78+
except Exception as exc:
79+
notify_exc_by_email(exc)
80+
raise
81+
82+
example_flow()
83+
```
84+
85+
## Resources
86+
87+
For more tips on how to use tasks and flows in a Collection, check out [Using Collections](https://docs.prefect.io/collections/usage/)!
88+
89+
### Installation
90+
91+
Install `prefect-email` with `pip`:
92+
93+
```bash
94+
pip install prefect-email
95+
```
96+
97+
Then, register to [view the block](https://docs.prefect.io/ui/blocks/) on Prefect Cloud:
98+
99+
```bash
100+
prefect block register -m prefect_email
101+
```
102+
103+
Note, to use the `load` method on Blocks, you must already have a block document [saved through code](https://docs.prefect.io/concepts/blocks/#saving-blocks) or [saved through the UI](https://docs.prefect.io/ui/blocks/).
104+
105+
Requires an installation of Python 3.8+.
106+
107+
We recommend using a Python virtual environment manager such as pipenv, conda or virtualenv.
108+
109+
These tasks are designed to work with Prefect 2. For more information about how to use Prefect, please refer to the [Prefect documentation](https://docs.prefect.io/).
110+
111+
### Saving credentials to block
112+
113+
Note, to use the `load` method on Blocks, you must already have a block document [saved through code](https://docs.prefect.io/concepts/blocks/#saving-blocks) or [saved through the UI](https://docs.prefect.io/ui/blocks/).
114+
115+
Below is a walkthrough on saving block documents through code.
116+
117+
Create a short script, replacing the placeholders.
118+
119+
```python
120+
from prefect_email import EmailServerCredentials
121+
122+
credentials = EmailServerCredentials(
123+
username="EMAIL-ADDRESS-PLACEHOLDER",
124+
password="PASSWORD-PLACEHOLDER", # must be an app password
125+
)
126+
credentials.save("BLOCK-NAME-PLACEHOLDER")
127+
```
128+
129+
Congrats! You can now easily load the saved block, which holds your credentials:
130+
131+
```python
132+
from prefect_email import EmailServerCredentials
133+
134+
EmailServerCredentials.load("BLOCK_NAME_PLACEHOLDER")
135+
```
136+
137+
!!! info "Registering blocks"
138+
139+
Register blocks in this module to
140+
[view and edit them](https://docs.prefect.io/ui/blocks/)
141+
on Prefect Cloud:
142+
143+
```bash
144+
prefect block register -m prefect_email
145+
```

‎docs/integrations/prefect-email/message.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
::: prefect_email.message

‎mkdocs.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,11 @@ nav:
254254
- Jobs: integrations/prefect-databricks/jobs.md
255255
- Rest: integrations/prefect-databricks/rest.md
256256
- Flows: integrations/prefect-databricks/flows.md
257+
- Email:
258+
- integrations/prefect-email/index.md
259+
- Credentials: integrations/prefect-email/credentials.md
260+
- Message: integrations/prefect-email/message.md
261+
257262
- Shell:
258263
- integrations/prefect-shell/index.md
259264
- Commands: integrations/prefect-shell/commands.md

‎src/integrations/prefect-azure/tests/test_version.py

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
from packaging.version import Version
2+
3+
4+
def test_version():
5+
from prefect_azure import __version__
6+
7+
assert isinstance(__version__, str)
8+
assert Version(__version__)
9+
assert __version__.startswith("0.")

‎src/integrations/prefect-email/README.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# prefect-email
2+
3+
<p align="center">
4+
<a href="https://pypi.python.org/pypi/prefect-email/" alt="PyPI version">
5+
<img alt="PyPI" src="https://img.shields.io/pypi/v/prefect-email?color=0052FF&labelColor=090422"></a>
6+
<a href="https://pepy.tech/badge/prefect-email/" alt="Downloads">
7+
<img src="https://img.shields.io/pypi/dm/prefect-email?color=0052FF&labelColor=090422" /></a>
8+
</p>
9+
10+
Visit the full docs [here](https://PrefectHQ.github.io/prefect-email) to see additional examples and the API reference.
11+
12+
`prefect-email` is a collection of prebuilt Prefect integrations that can be used to interact with email services.
13+
14+
## Getting Started
15+
16+
### Integrate with Prefect flows
17+
18+
`prefect-email` makes sending emails effortless, giving you peace of mind that your emails are being sent as expected.
19+
20+
First, install [prefect-email](#installation) and [save your email credentials to a block](#saving-credentials-to-block) to run the examples below!
21+
22+
```python
23+
from prefect import flow
24+
from prefect_email import EmailServerCredentials, email_send_message
25+
26+
@flow
27+
def example_email_send_message_flow(email_addresses):
28+
email_server_credentials = EmailServerCredentials.load("BLOCK-NAME-PLACEHOLDER")
29+
for email_address in email_addresses:
30+
subject = email_send_message.with_options(name=f"email {email_address}").submit(
31+
email_server_credentials=email_server_credentials,
32+
subject="Example Flow Notification using Gmail",
33+
msg="This proves email_send_message works!",
34+
email_to=email_address,
35+
)
36+
37+
example_email_send_message_flow(["EMAIL-ADDRESS-PLACEHOLDER"])
38+
```
39+
40+
Outputs:
41+
42+
```bash
43+
16:58:27.646 | INFO | prefect.engine - Created flow run 'busy-bat' for flow 'example-email-send-message-flow'
44+
16:58:29.225 | INFO | Flow run 'busy-bat' - Created task run 'email someone@gmail.com-0' for task 'email someone@gmail.com'
45+
16:58:29.229 | INFO | Flow run 'busy-bat' - Submitted task run 'email someone@gmail.com-0' for execution.
46+
16:58:31.523 | INFO | Task run 'email someone@gmail.com-0' - Finished in state Completed()
47+
16:58:31.713 | INFO | Flow run 'busy-bat' - Finished in state Completed('All states completed.')
48+
```
49+
50+
Please note, many email services, like Gmail, require an [App Password](https://support.google.com/accounts/answer/185833) to successfully send emails. If you encounter an error similar to `smtplib.SMTPAuthenticationError: (535, b'5.7.8 Username and Password not accepted...`, it's likely you are not using an App Password.
51+
52+
### Capture exceptions and notify by email
53+
54+
Perhaps you want an email notification with the details of the exception when your flow run fails.
55+
56+
`prefect-email` can be wrapped in an `except` statement to do just that!
57+
58+
```python
59+
from prefect import flow
60+
from prefect.context import get_run_context
61+
from prefect_email import EmailServerCredentials, email_send_message
62+
63+
def notify_exc_by_email(exc):
64+
context = get_run_context()
65+
flow_run_name = context.flow_run.name
66+
email_server_credentials = EmailServerCredentials.load("email-server-credentials")
67+
email_send_message(
68+
email_server_credentials=email_server_credentials,
69+
subject=f"Flow run {flow_run_name!r} failed",
70+
msg=f"Flow run {flow_run_name!r} failed due to {exc}.",
71+
email_to=email_server_credentials.username,
72+
)
73+
74+
@flow
75+
def example_flow():
76+
try:
77+
1 / 0
78+
except Exception as exc:
79+
notify_exc_by_email(exc)
80+
raise
81+
82+
example_flow()
83+
```
84+
85+
## Resources
86+
87+
For more tips on how to use tasks and flows in a Collection, check out [Using Collections](https://docs.prefect.io/collections/usage/)!
88+
89+
### Installation
90+
91+
Install `prefect-email` with `pip`:
92+
93+
```bash
94+
pip install prefect-email
95+
```
96+
97+
Then, register to [view the block](https://docs.prefect.io/ui/blocks/) on Prefect Cloud:
98+
99+
```bash
100+
prefect block register -m prefect_email
101+
```
102+
103+
Note, to use the `load` method on Blocks, you must already have a block document [saved through code](https://docs.prefect.io/concepts/blocks/#saving-blocks) or [saved through the UI](https://docs.prefect.io/ui/blocks/).
104+
105+
Requires an installation of Python 3.8+.
106+
107+
We recommend using a Python virtual environment manager such as pipenv, conda or virtualenv.
108+
109+
These tasks are designed to work with Prefect 2. For more information about how to use Prefect, please refer to the [Prefect documentation](https://docs.prefect.io/).
110+
111+
### Saving credentials to block
112+
113+
Note, to use the `load` method on Blocks, you must already have a block document [saved through code](https://docs.prefect.io/concepts/blocks/#saving-blocks) or [saved through the UI](https://docs.prefect.io/ui/blocks/).
114+
115+
Below is a walkthrough on saving block documents through code.
116+
117+
Create a short script, replacing the placeholders.
118+
119+
```python
120+
from prefect_email import EmailServerCredentials
121+
122+
credentials = EmailServerCredentials(
123+
username="EMAIL-ADDRESS-PLACEHOLDER",
124+
password="PASSWORD-PLACEHOLDER", # must be an app password
125+
)
126+
credentials.save("BLOCK-NAME-PLACEHOLDER")
127+
```
128+
129+
Congrats! You can now easily load the saved block, which holds your credentials:
130+
131+
```python
132+
from prefect_email import EmailServerCredentials
133+
134+
EmailServerCredentials.load("BLOCK_NAME_PLACEHOLDER")
135+
```
136+
137+
!!! info "Registering blocks"
138+
139+
Register blocks in this module to
140+
[view and edit them](https://docs.prefect.io/ui/blocks/)
141+
on Prefect Cloud:
142+
143+
```bash
144+
prefect block register -m prefect_email
145+
```

‎src/integrations/prefect-email/prefect_email/__init__.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
from . import _version
2+
from .credentials import EmailServerCredentials, SMTPServer, SMTPType
3+
from .message import email_send_message
4+
5+
__version__ = _version.__version__
6+
7+
__all__ = ["EmailServerCredentials", "SMTPServer", "SMTPType", "email_send_message"]

0 commit comments

Comments
 (0)