Added limited type stubs for mypy (#402)

apprise/Apprise.pyi

@@ -0,0 +1,63 @@
+from typing import Any, Dict, List, Iterable, Iterator, Optional
+
+from . import (AppriseAsset, AppriseAttachment, AppriseConfig, ConfigBase,
+               NotifyBase, NotifyFormat, NotifyType)
+from .common import ContentLocation
+
+_Server = Union[str, ConfigBase, NotifyBase, AppriseConfig]
+_Servers = Union[_Server, Dict[Any, _Server], Iterable[_Server]]
+# Can't define this recursively as mypy doesn't support recursive types:
+# https://github.com/python/mypy/issues/731
+_Tag = Union[str, Iterable[Union[str, Iterable[str]]]]
+
+class Apprise:
+    def __init__(
+        self,
+        servers: _Servers = ...,
+        asset: Optional[AppriseAsset] = ...,
+        location: Optional[ContentLocation] = ...,
+        debug: bool = ...
+    ) -> None: ...
+    @staticmethod
+    def instantiate(
+        url: Union[str, Dict[str, NotifyBase]],
+        asset: Optional[AppriseAsset] = ...,
+        tag: Optional[_Tag] = ...,
+        suppress_exceptions: bool = ...
+    ) -> NotifyBase: ...
+    def add(
+        self,
+        servers: _Servers = ...,
+        asset: Optional[AppriseAsset] = ...,
+        tag: Optional[_Tag] = ...
+    ) -> bool: ...
+    def clear(self) -> None: ...
+    def find(self, tag: str = ...) -> Iterator[Apprise]: ...
+    def notify(
+        self,
+        body: str,
+        title: str = ...,
+        notify_type: NotifyType = ...,
+        body_format: NotifyFormat = ...,
+        tag: _Tag = ...,
+        attach: Optional[AppriseAttachment] = ...,
+        interpret_escapes: Optional[bool] = ...
+    ) -> bool: ...
+    async def async_notify(
+        self,
+        body: str,
+        title: str = ...,
+        notify_type: NotifyType = ...,
+        body_format: NotifyFormat = ...,
+        tag: _Tag = ...,
+        attach: Optional[AppriseAttachment] = ...,
+        interpret_escapes: Optional[bool] = ...
+    ) -> bool: ...
+    def details(self, lang: Optional[str] = ...) -> Dict[str, Any]: ...
+    def urls(self, privacy: bool = ...) -> Iterable[str]: ...
+    def pop(self, index: int) -> ConfigBase: ...
+    def __getitem__(self, index: int) -> ConfigBase: ...
+    def __bool__(self) -> bool: ...
+    def __nonzero__(self) -> bool: ...
+    def __iter__(self) -> Iterator[ConfigBase]: ...
+    def __len__(self) -> int: ...

apprise/AppriseAsset.pyi

@@ -0,0 +1,34 @@
+from typing import Dict, Optional
+
+from . import NotifyFormat, NotifyType
+
+class AppriseAsset:
+    app_id: str
+    app_desc: str
+    app_url: str
+    html_notify_map: Dict[NotifyType, str]
+    default_html_color: str
+    default_extension: str
+    theme: Optional[str]
+    image_url_mask: str
+    image_url_logo: str
+    image_path_mask: Optional[str]
+    body_format: Optional[NotifyFormat]
+    async_mode: bool
+    interpret_escapes: bool
+    def __init__(
+        self,
+        app_id: str = ...,
+        app_desc: str = ...,
+        app_url: str = ...,
+        html_notify_map: Dict[NotifyType, str] = ...,
+        default_html_color: str = ...,
+        default_extension: str = ...,
+        theme: Optional[str] = ...,
+        image_url_mask: str = ...,
+        image_url_logo: str = ...,
+        image_path_mask: Optional[str] = ...,
+        body_format: Optional[NotifyFormat] = ...,
+        async_mode: bool = ...,
+        interpret_escapes: bool = ...
+    ) -> None: ...

apprise/AppriseAttachment.pyi

@@ -0,0 +1,38 @@
+from typing import Any, Iterable, Optional, Union
+
+from . import AppriseAsset, ContentLocation
+from .attachment import AttachBase
+
+_Attachment = Union[str, AttachBase]
+_Attachments = Iterable[_Attachment]
+
+class AppriseAttachment:
+    def __init__(
+        self,
+        paths: Optional[_Attachments] = ...,
+        asset: Optional[AppriseAttachment] = ...,
+        cache: bool = ...,
+        location: Optional[ContentLocation] = ...,
+        **kwargs: Any
+    ) -> None: ...
+    def add(
+        self,
+        attachments: _Attachments,
+        asset: Optional[AppriseAttachment] = ...,
+        cache: Optional[bool] = ...
+    ) -> bool: ...
+    @staticmethod
+    def instantiate(
+        url: str,
+        asset: Optional[AppriseAsset] = ...,
+        cache: Optional[bool] = ...,
+        suppress_exceptions: bool = ...
+    ) -> NotifyBase: ...
+    def clear(self) -> None: ...
+    def size(self) -> int: ...
+    def pop(self, index: int = ...) -> AttachBase: ...
+    def __getitem__(self, index: int) -> AttachBase: ...
+    def __bool__(self) -> bool: ...
+    def __nonzero__(self) -> bool: ...
+    def __iter__(self) -> Iterator[AttachBase]: ...
+    def __len__(self) -> int: ...

apprise/AppriseConfig.pyi

@@ -0,0 +1,49 @@
+from typing import Any, Iterable, Iterator, List, Optional, Union
+
+from . import AppriseAsset, NotifyBase
+from .config import ConfigBase
+
+_Configs = Union[ConfigBase, str, Iterable[str]]
+
+class AppriseConfig:
+    def __init__(
+        self,
+        paths: Optional[_Configs] = ...,
+        asset: Optional[AppriseAsset] = ...,
+        cache: bool = ...,
+        recursion: int = ...,
+        insecure_includes: bool = ...,
+        **kwargs: Any
+    ) -> None: ...
+    def add(
+        self,
+        configs: _Configs,
+        asset: Optional[AppriseAsset] = ...,
+        cache: bool = ...,
+        recursion: Optional[bool] = ...,
+        insecure_includes: Optional[bool] = ...
+    ) -> bool: ...
+    def add_config(
+        self,
+        content: str,
+        asset: Optional[AppriseAsset] = ...,
+        tag: Optional[str] = ...,
+        format: Optional[str] = ...,
+        recursion: Optional[int] = ...,
+        insecure_includes: Optional[bool] = ...
+    ) -> bool: ...
+    def servers(self, tag: str = ..., *args: Any, **kwargs: Any) -> List[ConfigBase]: ...
+    def instantiate(
+        url: str,
+        asset: Optional[AppriseAsset] = ...,
+        tag: Optional[str] = ...,
+        cache: Optional[bool] = ...
+    ) -> NotifyBase: ...
+    def clear(self) -> None: ...
+    def server_pop(self, index: int) -> ConfigBase: ...
+    def pop(self, index: int = ...) -> ConfigBase: ...
+    def __getitem__(self, index: int) -> ConfigBase: ...
+    def __bool__(self) -> bool: ...
+    def __nonzero__(self) -> bool: ...
+    def __iter__(self) -> Iterator[ConfigBase]: ...
+    def __len__(self) -> int: ...

apprise/URLBase.pyi

@@ -0,0 +1,16 @@
+from logging import logger
+from typing import Any, Iterable, Set, Optional
+
+class URLBase:
+    service_name: Optional[str]
+    protocol: Optional[str]
+    secure_protocol: Optional[str]
+    request_rate_per_sec: int
+    socket_connect_timeout: float
+    socket_read_timeout: float
+    tags: Set[str]
+    verify_certificate: bool
+    logger: logger
+    def url(self, privacy: bool = ..., *args: Any, **kwargs: Any) -> str: ...
+    def __contains__(self, tags: Iterable[str]) -> bool: ...
+    def __str__(self) -> str: ...

apprise/attachment/AttachBase.pyi

@@ -0,0 +1,37 @@
+from typing import Any, Dict, Optional
+
+from .. import ContentLocation
+
+class AttachBase:
+    max_detect_buffer_size: int
+    unknown_mimetype: str
+    unknown_filename: str
+    unknown_filename_extension: str
+    strict: bool
+    max_file_size: int
+    location: ContentLocation
+    template_args: Dict[str, Any]
+    def __init__(
+        self,
+        name: Optional[str] = ...,
+        mimetype: Optional[str] = ...,
+        cache: Optional[bool] = ...,
+        **kwargs: Any
+    ) -> None: ...
+    @property
+    def path(self) -> Optional[str]: ...
+    @property
+    def name(self) -> Optional[str]: ...
+    @property
+    def mimetype(self) -> Optional[str]: ...
+    def exists(self) -> bool: ...
+    def invalidate(self) -> None: ...
+    def download(self) -> bool: ...
+    @staticmethod
+    def parse_url(
+        url: str,
+        verify_host: bool = ...
+    ) -> Dict[str, Any]: ...
+    def __len__(self) -> int: ...
+    def __bool__(self) -> bool: ...
+    def __nonzero__(self) -> bool: ...

apprise/common.pyi

@@ -0,0 +1,15 @@
+class NotifyType:
+    INFO: NotifyType
+    SUCCESS: NotifyType
+    WARNING: NotifyType
+    FAILURE: NotifyType
+
+class NotifyFormat:
+    TEXT: NotifyFormat
+    HTML: NotifyFormat
+    MARKDOWN: NotifyFormat
+
+class ContentLocation:
+    LOCAL: ContentLocation
+    HOSTED: ContentLocation
+    INACCESSIBLE: ContentLocation

apprise/config/ConfigBase.pyi

@@ -0,0 +1,3 @@
+from .. import URLBase
+
+class ConfigBase(URLBase): ...

apprise/plugins/NotifyBase.pyi

@@ -0,0 +1 @@
+class NotifyBase: ...