sygmail 0.1.0__py3-none-any.whl

sygmail/__init__.py

@@ -0,0 +1,3 @@
+from .client import Sygmail, SygmailConfig
+
+__all__ = ["Sygmail", "SygmailConfig"]

sygmail/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sygmail/cli.py

@@ -0,0 +1,160 @@
+import argparse
+import sys
+from typing import List, Optional
+
+from .client import Sygmail
+
+CLI_DEFAULT_CONTENTS = "[sygmail notification]"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="sygmail", description="Send Gmail notifications.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    send_parser = subparsers.add_parser("send", help="Send a notification email")
+    send_parser.add_argument("--env", default=".env", help="Path to .env file")
+    send_parser.add_argument("--from", dest="from_addr", help="From address")
+    send_parser.add_argument("--to", help="To address")
+    send_parser.add_argument("--subject", help="Email subject")
+    send_parser.add_argument("--contents", help="Email contents")
+    send_parser.add_argument(
+        "--attachments",
+        nargs="*",
+        default=None,
+        help="Attachment file paths",
+    )
+    send_parser.add_argument(
+        "--attachments-path",
+        dest="attachments_path",
+        help="Path to auto-attach files",
+    )
+
+    config_parser = subparsers.add_parser("config", help="Manage .env configuration")
+    config_subparsers = config_parser.add_subparsers(dest="config_command", required=True)
+
+    config_set_parser = config_subparsers.add_parser("set", help="Set config values")
+    config_set_parser.add_argument("--env", default=".env", help="Path to .env file")
+    config_set_parser.add_argument("--from", dest="from_addr", help="From address")
+    config_set_parser.add_argument("--app-password", help="Gmail app password")
+    config_set_parser.add_argument("--to", help="To address")
+    config_set_parser.add_argument("--subject", help="Email subject")
+    config_set_parser.add_argument("--contents", help="Email contents")
+    config_set_parser.add_argument(
+        "--attachments-path",
+        dest="attachments_path",
+        help="Path to auto-attach files",
+    )
+
+    config_reset_parser = config_subparsers.add_parser(
+        "reset",
+        help="Reset subject/contents to defaults",
+    )
+    config_reset_parser.add_argument("--env", default=".env", help="Path to .env file")
+
+    config_show_parser = config_subparsers.add_parser(
+        "show",
+        help="Show current config values",
+    )
+    config_show_parser.add_argument("--env", default=".env", help="Path to .env file")
+    config_show_parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Show secrets without masking",
+    )
+
+    return parser
+
+
+def run_send(args: argparse.Namespace) -> int:
+    syg = Sygmail(env_path=args.env)
+
+    contents = args.contents
+    if contents is None:
+        contents = CLI_DEFAULT_CONTENTS
+
+    attachments = _normalize_attachments_arg(args.attachments)
+
+    syg.send(
+        from_addr=args.from_addr,
+        to=args.to,
+        subject=args.subject,
+        contents=contents,
+        attachments=attachments,
+        attachments_path=args.attachments_path,
+    )
+    return 0
+
+
+def _normalize_attachments_arg(raw: Optional[List[str]]) -> Optional[List[str]]:
+    if raw is None:
+        return None
+    if len(raw) == 0:
+        return []
+    return raw
+
+
+def _mask_secret(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    if len(value) <= 4:
+        return "****"
+    return f"****{value[-4:]}"
+
+
+def run_config_set(args: argparse.Namespace) -> int:
+    syg = Sygmail(env_path=args.env)
+    syg.configure(
+        from_addr=args.from_addr,
+        app_password=args.app_password,
+        to=args.to,
+        subject=args.subject,
+        contents=args.contents,
+        attachments_path=args.attachments_path,
+        persist=True,
+    )
+    return 0
+
+
+def run_config_reset(args: argparse.Namespace) -> int:
+    syg = Sygmail(env_path=args.env)
+    syg.reset_subject_contents(persist=True)
+    return 0
+
+
+def run_config_show(args: argparse.Namespace) -> int:
+    syg = Sygmail(env_path=args.env)
+    config = syg.config
+
+    app_password = config.app_password
+    if not args.raw:
+        app_password = _mask_secret(app_password)
+
+    print(f"SYGMAIL_FROM={config.from_addr or ''}")
+    print(f"SYGMAIL_APP_PASSWORD={app_password or ''}")
+    print(f"SYGMAIL_TO={config.to or ''}")
+    print(f"SYGMAIL_SUBJECT={config.subject or ''}")
+    print(f"SYGMAIL_CONTENTS={config.contents or ''}")
+    print(f"SYGMAIL_ATTACHMENTS_PATH={config.attachments_path or ''}")
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "send":
+        return run_send(args)
+    if args.command == "config":
+        if args.config_command == "set":
+            return run_config_set(args)
+        if args.config_command == "reset":
+            return run_config_reset(args)
+        if args.config_command == "show":
+            return run_config_show(args)
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

sygmail/client.py

@@ -0,0 +1,247 @@
+import os
+import sys
+import warnings
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+import yagmail
+
+DEFAULT_SUBJECT = "Process Completed"
+DEFAULT_CONTENTS_TEMPLATE = "{script_name} has finished running."
+
+ENV_KEYS = {
+    "from_addr": "SYGMAIL_FROM",
+    "app_password": "SYGMAIL_APP_PASSWORD",
+    "to": "SYGMAIL_TO",
+    "subject": "SYGMAIL_SUBJECT",
+    "contents": "SYGMAIL_CONTENTS",
+    "attachments_path": "SYGMAIL_ATTACHMENTS_PATH",
+}
+
+
+@dataclass
+class SygmailConfig:
+    from_addr: Optional[str] = None
+    app_password: Optional[str] = None
+    to: Optional[str] = None
+    subject: Optional[str] = None
+    contents: Optional[str] = None
+    attachments_path: Optional[str] = None
+
+    @classmethod
+    def load(cls, env_path: str = ".env") -> "SygmailConfig":
+        file_values = _read_env_file(env_path)
+        values = {**file_values}
+        for field, key in ENV_KEYS.items():
+            env_value = os.environ.get(key)
+            if env_value is None:
+                env_value = os.environ.get(key.lower())
+            if env_value is not None:
+                values[field] = env_value
+        return cls(
+            from_addr=values.get("from_addr"),
+            app_password=values.get("app_password"),
+            to=values.get("to"),
+            subject=values.get("subject"),
+            contents=values.get("contents"),
+            attachments_path=values.get("attachments_path"),
+        )
+
+    def save(self, env_path: str = ".env") -> None:
+        data = {
+            ENV_KEYS["from_addr"]: self.from_addr or "",
+            ENV_KEYS["app_password"]: self.app_password or "",
+            ENV_KEYS["to"]: self.to or "",
+            ENV_KEYS["subject"]: self.subject or DEFAULT_SUBJECT,
+            ENV_KEYS["contents"]: self.contents or DEFAULT_CONTENTS_TEMPLATE,
+        }
+        if self.attachments_path is not None:
+            data[ENV_KEYS["attachments_path"]] = self.attachments_path
+        _write_env_file(env_path, data)
+
+    def reset_subject_contents(self) -> None:
+        self.subject = DEFAULT_SUBJECT
+        self.contents = DEFAULT_CONTENTS_TEMPLATE
+
+
+class Sygmail:
+    def __init__(self, config: Optional[SygmailConfig] = None, env_path: str = ".env") -> None:
+        self.env_path = env_path
+        self.config = config or SygmailConfig.load(env_path)
+
+    def configure(
+        self,
+        *,
+        from_addr: Optional[str] = None,
+        from_: Optional[str] = None,
+        app_password: Optional[str] = None,
+        to: Optional[str] = None,
+        subject: Optional[str] = None,
+        contents: Optional[str] = None,
+        attachments_path: Optional[str] = None,
+        persist: bool = True,
+    ) -> None:
+        if from_addr is None and from_ is not None:
+            from_addr = from_
+        if from_addr is not None:
+            self.config.from_addr = from_addr
+        if app_password is not None:
+            self.config.app_password = app_password
+        if to is not None:
+            self.config.to = to
+        if subject is not None:
+            self.config.subject = subject
+        if contents is not None:
+            self.config.contents = contents
+        if attachments_path is not None:
+            self.config.attachments_path = attachments_path
+        if persist:
+            self.config.save(self.env_path)
+
+    def reset_subject_contents(self, persist: bool = True) -> None:
+        self.config.reset_subject_contents()
+        if persist:
+            self.config.save(self.env_path)
+
+    def send(
+        self,
+        *,
+        from_addr: Optional[str] = None,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        subject: Optional[str] = None,
+        contents: Optional[str] = None,
+        attachments: Optional[Iterable[str]] = None,
+        attachments_path: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        resolved_from = from_addr or from_ or self.config.from_addr
+        app_password = self.config.app_password
+        target = to or self.config.to or resolved_from
+
+        if not resolved_from or not app_password or not target:
+            raise ValueError("from_addr and app_password are required")
+
+        script_name = _get_script_name()
+        subject_value = subject or self.config.subject or DEFAULT_SUBJECT
+        contents_value = contents or self.config.contents or DEFAULT_CONTENTS_TEMPLATE
+        contents_value = _render_contents(contents_value, script_name)
+
+        attachments_list = _normalize_attachments(attachments)
+        path_value = attachments_path or self.config.attachments_path
+        if attachments is None and path_value:
+            attachments_list.extend(_collect_attachments(path_value))
+
+        yag = yagmail.SMTP(resolved_from, app_password)
+        yag.send(
+            to=target,
+            subject=subject_value,
+            contents=contents_value,
+            attachments=attachments_list if attachments_list else None,
+            **kwargs,
+        )
+
+
+def _get_script_name() -> str:
+    raw = sys.argv[0] if sys.argv and sys.argv[0] else "script"
+    return os.path.basename(raw)
+
+
+def _render_contents(contents: str, script_name: str) -> str:
+    if "{script_name}" in contents:
+        try:
+            return contents.format(script_name=script_name)
+        except Exception:
+            return contents
+    return contents
+
+
+def _normalize_attachments(attachments: Optional[Iterable[str]]) -> List[str]:
+    if not attachments:
+        return []
+    if isinstance(attachments, (str, bytes, os.PathLike)):
+        existing, missing = _filter_existing_paths([str(attachments)])
+        _warn_missing_attachments(missing)
+        return existing
+    existing, missing = _filter_existing_paths([str(item) for item in attachments])
+    _warn_missing_attachments(missing)
+    return existing
+
+
+def _collect_attachments(attachments_path: str) -> List[str]:
+    path = Path(attachments_path)
+    if not path.exists():
+        _warn_missing_attachments([str(path)])
+        return []
+    if path.is_file():
+        existing, missing = _filter_existing_paths([str(path)])
+        _warn_missing_attachments(missing)
+        return existing
+    existing, missing = _filter_existing_paths([str(child) for child in path.iterdir() if child.is_file()])
+    _warn_missing_attachments(missing)
+    return existing
+
+
+def _filter_existing_paths(paths: Iterable[str]) -> tuple[List[str], List[str]]:
+    existing: List[str] = []
+    missing: List[str] = []
+    for value in paths:
+        try:
+            if Path(value).is_file():
+                existing.append(value)
+            else:
+                missing.append(value)
+        except OSError:
+            missing.append(value)
+    return existing, missing
+
+
+def _warn_missing_attachments(paths: Iterable[str]) -> None:
+    missing = [path for path in paths if path]
+    if not missing:
+        return
+    joined = ", ".join(missing)
+    warnings.warn(f"missing attachments ignored: {joined}", stacklevel=3)
+
+
+def _read_env_file(env_path: str) -> dict:
+    path = Path(env_path)
+    if not path.exists():
+        return {}
+
+    values = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if "=" not in stripped:
+            continue
+        key, value = stripped.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip("\"'")
+        if not key:
+            continue
+        normalized_key = _normalize_env_key(key)
+        if normalized_key in ENV_KEYS.values():
+            field = _env_key_to_field(normalized_key)
+            if field:
+                values[field] = value
+    return values
+
+
+def _write_env_file(env_path: str, data: dict) -> None:
+    path = Path(env_path)
+    lines = [f"{key}={value}" for key, value in data.items()]
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def _normalize_env_key(key: str) -> str:
+    return key.upper()
+
+
+def _env_key_to_field(env_key: str) -> Optional[str]:
+    for field, key in ENV_KEYS.items():
+        if key == env_key:
+            return field
+    return None

sygmail-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: sygmail
+Version: 0.1.0
+Summary: Lightweight Gmail notification wrapper
+Author-email: Satoshi Nakabayashi <3104nkb@gmail.com>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yagmail
+Dynamic: license-file
+
+# sygmail
+
+Lightweight wrapper for sending Gmail notifications with simple defaults and a .env config.
+
+## Features
+
+- Load settings from `.env` and environment variables
+- Save settings from code (`persist=True`)
+- Defaults for subject/contents with `{script_name}` placeholder
+- Optional auto-attachments from a path
+
+## Install
+
+```
+pip install sygmail
+```
+
+## Requirements
+
+- Python 3.9+
+- Dependency: `yagmail`
+
+## Quick start
+
+```python
+from sygmail import Sygmail
+
+syg = Sygmail()
+syg.configure(
+    from_addr="you@gmail.com",
+    app_password="app-password",
+    persist=True,
+)
+syg.send()
+```
+
+## .env keys
+
+```
+SYGMAIL_FROM=you@gmail.com
+SYGMAIL_APP_PASSWORD=app-password
+SYGMAIL_TO=to@example.com
+SYGMAIL_SUBJECT=Process Completed
+SYGMAIL_CONTENTS={script_name} has finished running.
+SYGMAIL_ATTACHMENTS_PATH=./a/
+```
+
+## Defaults
+
+- Subject: `Process Completed`
+- Contents: `{script_name} has finished running.`
+
+Reset back to defaults:
+
+```python
+syg.reset_subject_contents(persist=True)
+```
+
+## Attachments behavior
+
+- If `attachments` is provided in `send()`, it is used as-is.
+- If `attachments` is not provided, and `SYGMAIL_ATTACHMENTS_PATH` is set,
+  files under that path are attached (files only, no folders).
+
+Examples:
+
+```python
+syg.send(attachments=["./a/file.txt"])  # use only this
+syg.send(attachments=[])               # explicitly no attachments
+syg.send()                             # auto-attach from SYGMAIL_ATTACHMENTS_PATH if set
+```
+
+## CLI
+
+Use `python -m sygmail` for now:
+
+```
+python -m sygmail send
+```
+
+Options:
+
+```
+python -m sygmail send \
+    --env .env \
+    --from you@gmail.com \
+    --to to@example.com \
+    --subject "Process Completed" \
+    --contents "[sygmail notification]" \
+    --attachments ./path/to/file \
+    --attachments-path ./path/to/folder/
+```
+
+- If `--contents` is omitted, CLI uses `[sygmail notification]` without editing `.env`.
+
+Common examples:
+
+```
+python -m sygmail send
+
+python -m sygmail send --subject "Job Done" --contents "[sygmail notification]"
+
+python -m sygmail send --attachments ./a/a.txt ./a/b.txt
+
+python -m sygmail config set --from you@gmail.com --app-password "app-password"
+
+python -m sygmail config show
+```
+
+Config commands:
+
+```
+python -m sygmail config set \
+    --env .env \
+    --from you@gmail.com \
+    --app-password "app-password" \
+    --to to@example.com \
+    --subject "Process Completed" \
+    --contents "{script_name} has finished running." \
+    --attachments-path ./a/
+
+python -m sygmail config reset --env .env
+
+python -m sygmail config show --env .env
+
+python -m sygmail config show --env .env --raw
+```
+
+## API
+
+```python
+Sygmail(env_path=".env")
+Sygmail.configure(
+    from_addr=None,
+    from_=None,
+    app_password=None,
+    to=None,
+    subject=None,
+    contents=None,
+    attachments_path=None,
+    persist=True,
+)
+Sygmail.reset_subject_contents(persist=True)
+Sygmail.send(
+    from_addr=None,
+    from_=None,
+    to=None,
+    subject=None,
+    contents=None,
+    attachments=None,
+    attachments_path=None,
+    **kwargs,
+)
+```
+
+## Notes
+
+- Use a Gmail app password (not your normal password).
+- Settings are stored in `.env` in the current working directory by default.
+- If `to` is omitted, the message is sent to the same address as `from_addr`.
+
+## Security
+
+- Do not commit `.env` to public repos.
+- Treat app passwords like secrets.
+
+## Operations
+
+- Prefer `chmod 600 .env` on shared machines.
+- Use `--env` to separate configs per project.

sygmail-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sygmail/__init__.py,sha256=eGoC5SwKCqe1cYhH1LuNPogYeeOTd636Wlnt70nRRB8,83
+sygmail/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+sygmail/cli.py,sha256=rafYsPIfx55WNnaoO6hgNJZpl0jsxNeZJLxZeIk3hbk,4965
+sygmail/client.py,sha256=lLO72zkAIp2MsO-SYh8_HwdOGP7GNEKaLvPBZ8wlqpE,8190
+sygmail-0.1.0.dist-info/licenses/LICENSE,sha256=Oakmmh4GWfLsNpdR0BBBCzmhIf_3rEeIjrB_hvolczk,1076
+sygmail-0.1.0.dist-info/METADATA,sha256=356x36EyQ6pp3vcC57EjlKNKvzd-FH5frZlIsu77xuk,3755
+sygmail-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+sygmail-0.1.0.dist-info/entry_points.txt,sha256=_6WdaniMLQk9VEx1MnYSNXMIyt7Csce2-PG6mopUGtI,45
+sygmail-0.1.0.dist-info/top_level.txt,sha256=umbnP2FZMQ4N-tovcks9rAP1oN3XW7wu3TyDWq1rw-8,8
+sygmail-0.1.0.dist-info/RECORD,,

sygmail-0.1.0.dist-info/WHEEL

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

sygmail-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sygmail = sygmail.cli:main

sygmail-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satoshi Nakabayashi
+
+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.

sygmail-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sygmail