Metadata-Version: 1.1
Name: qcloudsms-py
Version: 0.1.3
Summary: qcloudsms python sdk
Home-page: https://gitub.com/qcloudsms/qcloudsms_py
Author: qcloudsms
Author-email: qcloudsms@gmail.com
License: https://opensource.org/licenses/MIT
Description: 腾讯云短信 Python SDK
        ===
        
        ## 腾讯短信服务
        
        目前`腾讯云短信`为客户提供`国内短信`、`国内语音`和`海外短信`三大服务，腾讯云短信SDK支持以下操作：
        
        ### 国内短信
        
        国内短信支持操作：
        
        - 单发短信
        - 指定模板单发短信
        - 群发短信
        - 指定模板群发短信
        - 拉取短信回执和短信回复状态
        
        > `Note` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)开通权限，量大客户可以使用此功能批量拉取，其他客户不建议使用。
        
        ### 海外短信
        
        海外短信支持操作：
        
        - 单发短信
        - 指定模板单发短信
        - 群发短信
        - 指定模板群发短信
        - 拉取短信回执和短信回复状态
        
        > `Note` 海外短信和国内短信使用同一接口，只需替换相应的国家码与手机号码，每次请求群发接口手机号码需全部为国内或者海外手机号码。
        
        ### 语音通知
        
        语音通知支持操作：
        
        - 发送语音验证码
        - 发送语音通知
        - 上传语音文件
        - 按语音文件fid发送语音通知
        - 指定模板发送语音通知类
        
        ## 开发
        
        ### 准备
        
        在开始开发云短信应用之前，需要准备如下信息:
        
        - [x] 获取SDK AppID和AppKey
        
        云短信应用SDK `AppID`和`AppKey`可在[短信控制台](https://console.cloud.tencent.com/sms)的应用信息里获取，如您尚未添加应用，请到[短信控制台](https://console.cloud.tencent.com/sms)中添加应用。
        
        - [x] 申请签名
        
        一个完整的短信由短信`签名`和短信正文内容两部分组成，短信`签名`须申请和审核，`签名`可在[短信控制台](https://console.cloud.tencent.com/sms)的相应服务模块`内容配置`中进行申请。
        
        - [x] 申请模板
        
        同样短信或语音正文内容`模板`须申请和审核，`模板`可在[短信控制台](https://console.cloud.tencent.com/sms)的相应服务模块`内容配置`中进行申请。
        
        ### 安装
        
        #### pip
        
        qcloudsms_py采用pip进行安装，要使用qcloudsms功能, 只需要执行:
        
        ```shell
        pip install qcloudsms_py
        ```
        
        #### 手动
        
        1. 手动下载或clone最新版本qcloudsms_py代码
        2. 在qcloudsms_py目录运行 `python setup.py install`或直接把qcloudsms_py所在目录加入`sys.path`
        
        > `Note` python2/python3都支持
        
        ### 文档
        
        若您对接口存在疑问，可以查阅:
        
        * [API开发指南](https://cloud.tencent.com/document/product/382/5808)
        * [SDK文档](https://qcloudsms.github.io/qcloudsms_py/)
        * [错误码](https://cloud.tencent.com/document/product/382/3771)
        
        ### 示例
        
        - **准备必要参数**
        
        ```python
        # 短信应用SDK AppID
        appid = 1400009099  # SDK AppID是1400开头
        
        # 短信应用SDK AppKey
        appkey = "9ff91d87c2cd7cd0ea762f141975d1df37481d48700d70ac37470aefc60f9bad"
        
        # 需要发送短信的手机号码
        phone_numbers = ["21212313123", "12345678902", "12345678903"]
        
        # 短信模板ID，需要在短信应用中申请
        template_id = 7839  # NOTE: 这里的模板ID`7839`只是一个示例，真实的模板ID需要在短信控制台中申请
        
        # 签名
        sms_sign = "腾讯云"  # NOTE: 这里的签名"腾讯云"只是一个示例，真实的签名需要在短信控制台中申请，另外签名参数使用的是`签名内容`，而不是`签名ID`
        ```
        
        - **单发短信**
        
        ```python
        from qcloudsms_py import SmsSingleSender
        from qcloudsms_py.httpclient import HTTPError
        
        sms_type = 0  # Enum{0: 普通短信, 1: 营销短信}
        ssender = SmsSingleSender(appid, appkey)
        try:
            result = ssender.send(sms_type, 86, phone_numbers[0],
                "【腾讯云】您的验证码是: 5678", extend="", ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        > `Note` 如需发送海外短信，同样可以使用此接口，只需将国家码 `86` 改写成对应国家码号。
        > `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过，才可能下发成功，否则返回失败。
        
        - **指定模板ID单发短信**
        
        ```python
        from qcloudsms_py import SmsSingleSender
        from qcloudsms_py.httpclient import HTTPError
        
        ssender = SmsSingleSender(appid, appkey)
        params = ["5678"]  # 当模板没有参数时，`params = []`
        try:
            result = ssender.send_with_param(86, phone_numbers[0],
                template_id, params, sign=sms_sign, extend="", ext="")  # 签名参数未提供或者为空时，会使用默认签名发送短信
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        > `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过，才可能下发成功，否则返回失败。
        
        - **群发**
        
        ```python
        from qcloudsms_py import SmsMultiSender
        from qcloudsms_py.httpclient import HTTPError
        
        sms_type = 0  # Enum{0: 普通短信, 1: 营销短信}
        msender = SmsMultiSender(appid, appkey)
        try:
            result = msender.send(sms_type, "86", phone_numbers,
                "【腾讯云】您的验证码是: 5678", extend="", ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        > `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过，才可能下发成功，否则返回失败。
        
        - **指定模板ID群发**
        
        ```python
        from qcloudsms_py import SmsMultiSender
        from qcloudsms_py.httpclient import HTTPError
        
        msender = SmsMultiSender(appid, appkey)
        params = ["5678"]
        try:
            result = msender.send_with_param(86, phone_numbers,
                template_id, params, sign=sms_sign, extend="", ext="")   # 签名参数未提供或者为空时，会使用默认签名发送短信
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        > `Note:`群发一次请求最多支持200个号码，如有对号码数量有特殊需求请联系腾讯云短信技术支持(QQ:3012203387)。
        > `Note` 无论单发/群发短信还是指定模板ID单发/群发短信都需要从控制台中申请模板并且模板已经审核通过，才可能下发成功，否则返回失败。
        
        - **发送语音验证码**
        
        ```python
        from qcloudsms_py import SmsVoiceVerifyCodeSender
        from qcloudsms_py.httpclient import HTTPError
        
        vvcsender = SmsVoiceVerifyCodeSender(appid, appkey)
        try:
            result = vvcsender.send("86", phone_numbers[0], "5678",
                playtimes=2, ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        > `Note` 语音验证码发送只需提供验证码数字，例如当msg=“5678”时，您收到的语音通知为“您的语音验证码是5678”，如需自定义内容，可以使用语音通知。
        
        
        - **发送语音通知**
        
        ```python
        from qcloudsms_py import SmsVoicePromptSender
        from qcloudsms_py.httpclient import HTTPError
        
        vpsender = SmsVoicePromptSender(appid, appkey)
        try:
            result = vpsender.send("86", phone_numbers[0], 2, "5678",
                playtimes=2, ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        - **拉取短信回执以及回复**
        
        ```python
        from qcloudsms_py import SmsStatusPuller
        from qcloudsms_py.httpclient import HTTPError
        
        max_num = 10  # 单次拉取最大量
        spuller = SmsStatusPuller(appid, appkey)
        try:
            # 拉取短信回执
            callback_result = spuller.pull_callback(max_num)
            # 拉取回复
            reply_result = spuller.pull_reply(max_num)
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(callback_result)
        print(reply_result)
        ```
        
        > `Note:` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)，量大客户可以使用此功能批量拉取，其他客户不建议使用。
        
        - **拉取单个手机短信状态**
        
        ```python
        from qcloudsms_py import SmsMobileStatusPuller
        from qcloudsms_py.httpclient import HTTPError
        
        begin_time = 1511125600  # 开始时间(unix timestamp)
        end_time = 1511841600    # 结束时间(unix timestamp)
        max_num = 10             # 单次拉取最大量
        mspuller = SmsMobileStatusPuller(appid, appkey)
        try:
            # 拉取短信回执
            callback_result = mspuller.pull_callback("86", phone_numbers[0],
                begin_time, end_time, max_num)
            # 拉取回复
            reply_result = mspuller.pull_reply("86", phone_numbers[0],
                begin_time, end_time, max_num)
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(callback_result)
        print(reply_result)
        ```
        
        > `Note:` 短信拉取功能需要联系腾讯云短信技术支持(QQ:3012203387)，量大客户可以使用此功能批量拉取，其他客户不建议使用。
        
        - **发送海外短信**
        
        海外短信与国内短信发送类似, 发送海外短信只需替换相应国家码。
        
        
        - **上传语音文件**
        
        ```python
        from qcloudsms_py import VoiceFileUploader
        from qcloudsms_py.httpclient import HTTPError
        
        # Note: 语音文件大小上传限制400K字节
        with open("/path/to/example.mp3", "rb") as f:
            content = f.read()
        uploader = VoiceFileUploader(appid, appkey)
        try:
            result = uploader.upload(content, content_type="mp3")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        # 上传成功后，result里会带有语音文件的fid
        print(result)
        ```
        
        > `Note` '语音文件上传'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通
        
        - **按语音文件fid发送语音通知**
        
        ```python
        from qcloudsms_py import FileVoiceSender
        from qcloudsms_py.httpclient import HTTPError
        
        # Note：这里fid来自`上传语音文件`接口返回的响应，要按语音
        #   文件fid发送语音通知，需要先上传语音文件获取fid
        fid = "c799d10a43ec109f02f2288ca3c85b79e7700c98.mp3"
        fvsender = FileVoiceSender(appid, appkey)
        try:
            result = fvsender.send(fid, phone_numbers[0],
                nationcode="86", playtimes=2, ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        > `Note` 按'语音文件fid发送语音通知'功能需要联系腾讯云短信技术支持(QQ:3012203387)才能开通
        
        - **指定模板发送语音通知**
        
        ```python
        from qcloudsms_py import TtsVoiceSender
        from qcloudsms_py.httpclient import HTTPError
        
        template_id = 12345
        params = ["5678"]
        tvsender = TtsVoiceSender(appid, appkey)
        Try:
            result = tvsender.send(template_id, params, phone_numbers[0],
                nationcode="86", playtimes=2, ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        #### 使用代理
        
        有的环境需要使用代理才能上网，可以指定HTTPSimpleClient的proxy参数来实现, 示例如下:
        
        ```python
        from qcloudsms_py import SmsSingleSender
        from qcloudsms_py.httpclient import HTTPSimpleClient, HTTPError
        
        httpclient = HTTPSimpleClient(proxy="www.proxysever.com:8080")
        ssender = SmsSingleSender(appid, appkey, httpclient=httpclient)
        template_id = 7839
        params = ["5678"]
        try:
            result = ssender.send_with_param(86, phone_numbers[0],
                template_id, params, sign=sms_sign, extend="", ext="")
        except HTTPError as e:
            print(e)
        except Exception as e:
            print(e)
        
        print(result)
        ```
        
        #### 统一创建对象
        
        短信和语音各类的对象可以通过 `qcloudsms_py.QcloudSms` 统一创建，这种
        方式可以避免创建对象时多次传入参数`appid` 和 `appkey`, 示例如下:
        
        ```python
        from qcloudsms_py import QcloudSms
        
        # 创建QcloudSms对象
        qcloudsms = QcloudSms(appid, appkey)
        
        # 创建单发短信(SmsSingleSender)对象
        ssender = qcloudsms.SmsSingleSender()
        
        # 创建上传语音文件(VoiceFileUploader)对象
        uploader = qcloudsms.VoiceFileUploader()
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
