Merge branch 'develop' into dependabot/pip/urllib3-1.26.18

.github/workflows/python-app.yml

@@ -5,9 +5,16 @@ name: Python application
 
 on:
   push:
-    branches: [ master ]
+    branches:
+      - '**'
+  create:
+    branches:
+      - '**'
+    tags:
+      - '**'
   pull_request:
-    branches: [ master ]
+    branches:
+      - master  # Run on pull requests targeting the master branch
 
 jobs:
   build:
@@ -31,6 +38,16 @@ jobs:
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+    - name: Check formatting
+      run: |
+        # stop the build if there are formatting is error in any python codes
+        # to check whether the codes are formatted or not before merge
+        pip install black==24.4.2
+        pip install click==8.1.7
+        python -m black -t py310 --check .
     - name: Test with pytest
       run: |
-        pytest
+        export GOOGLE_APPLICATION_CREDENTIALS=service-account.json
+        export FCM_TEST_PROJECT_ID=test
+        pip install . ".[test]"
+        python -m pytest .

CONTRIBUTING.rst

@@ -28,15 +28,15 @@ Some simple guidelines to follow when contributing code:
 Tests
 -----
 
-Before commiting your changes, please run the tests. For running the tests you need an FCM API key.
+Before commiting your changes, please run the tests. For running the tests you need a service account.
 
-**Please do not use an API key, which is used in production!** 
+**Please do not use a service account, which is used in production!**
 
 ::
 
     pip install . ".[test]"
 
-    export FCM_TEST_API_KEY=AAA...
+    export GOOGLE_APPLICATION_CREDENTIALS="service_account.json"
 
     python -m pytest
 

README.md

@@ -0,0 +1,151 @@
+# PyFCM
+
+[![version](http://img.shields.io/pypi/v/pyfcm.svg?style=flat-square)](https://pypi.python.org/pypi/pyfcm/)
+[![license](http://img.shields.io/pypi/l/pyfcm.svg?style=flat-square)](https://pypi.python.org/pypi/pyfcm/)
+
+Python client for FCM - Firebase Cloud Messaging (Android, iOS and Web)
+
+Firebase Cloud Messaging (FCM) is the new version of GCM. It inherits
+the reliable and scalable GCM infrastructure, plus new features. GCM
+users are strongly recommended to upgrade to FCM.
+
+Using FCM, you can notify a client app that new email or other data is
+available to sync. You can send notifications to drive user reengagement
+and retention. For use cases such as instant messaging, a message can
+transfer a payload of up to 4KB to a client app.
+
+For more information, visit:
+<https://firebase.google.com/docs/cloud-messaging/>
+
+## Links
+
+-   Project: <https://github.com/olucurious/pyfcm>
+-   PyPi: <https://pypi.python.org/pypi/pyfcm/>
+
+### Updates (Breaking Changes)
+
+-   MIGRATION TO FCM HTTP V1 (JUNE 2024):
+    <https://github.com/olucurious/PyFCM/releases/tag/2.0.0> (big
+    shoutout to @Subhrans for the PR, for more information:
+    <https://firebase.google.com/docs/cloud-messaging/migrate-v1>)
+-   MAJOR UPDATES (AUGUST 2017):
+    <https://github.com/olucurious/PyFCM/releases/tag/1.4.0>
+
+Installation ==========
+
+Install using pip:
+
+    pip install pyfcm
+
+    OR
+
+    pip install git+https://github.com/olucurious/PyFCM.git
+
+PyFCM supports Android, iOS and Web.
+
+## Features
+
+-   All FCM functionality covered
+-   Tornado support
+
+## Examples
+
+### Send notifications using the `FCMNotification` class
+
+``` python
+# Send to single device.
+from pyfcm import FCMNotification
+
+push_service = FCMNotification(service_account_file="<service-account-json-path>")
+
+# OR initialize with proxies
+
+proxy_dict = {
+          "http"  : "http://127.0.0.1",
+          "https" : "http://127.0.0.1",
+        }
+push_service = FCMNotification(service_account_file="<service-account-json-path>", proxy_dict=proxy_dict)
+
+# Your service account file can be gotten from:  https://console.firebase.google.com/u/0/project/_/settings/serviceaccounts/adminsdk
+
+fcm_token = "<fcm token>"
+notification_title = "Uber update"
+notification_body = "Hi John, your order is on the way!"
+notification_image = "https://example.com/image.png"
+result = push_service.notify(fcm_token=fcm_token, notification_title=notification_title, notification_body=notification_body, notification_image=notification_image)
+print result
+```
+
+### Send a data message
+
+``` python
+# With FCM, you can send two types of messages to clients:
+# 1. Notification messages, sometimes thought of as "display messages."
+# 2. Data messages, which are handled by the client app.
+# 3. Notification messages with optional data payload.
+
+# Client app is responsible for processing data messages. Data messages have only custom key-value pairs. (Python dict)
+# Data messages let developers send up to 4KB of custom key-value pairs.
+
+# Sending a notification with data message payload
+data_payload = {
+    "foo": "bar",
+    "body": "great match!",
+    "room": "PortugalVSDenmark"
+}
+# To a single device
+result = push_service.notify(fcm_token=fcm_token, notification_body=notification_body, data_payload=data_payload)
+
+# Sending a data message only payload, do NOT include notification_body also do NOT include notification body
+# To a single device
+result = push_service.notify(fcm_token=fcm_token, data_payload=data_payload)
+
+# Use notification messages when you want FCM to handle displaying a notification on your app's behalf.
+# Use data messages when you just want to process the messages only in your app.
+# PyFCM can send a message including both notification and data payloads.
+# In such cases, FCM handles displaying the notification payload, and the client app handles the data payload.
+```
+
+### Appengine users should define their environment
+
+``` python
+push_service = FCMNotification(api_key="<service-account-json-path>", proxy_dict=proxy_dict, env='app_engine')
+result = push_service.notify(fcm_token=fcm_token, notification_body=message)
+```
+
+### Sending a message to a topic
+
+``` python
+# Send a message to devices subscribed to a topic.
+result = push_service.notify(topic_name="news", notification_body=message)
+
+# Conditional topic messaging
+topic_condition = "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)"
+result = push_service.notify(notification_body=message, topic_condition=topic_condition)
+# FCM first evaluates any conditions in parentheses, and then evaluates the expression from left to right.
+# In the above expression, a user subscribed to any single topic does not receive the message. Likewise,
+# a user who does not subscribe to TopicA does not receive the message. These combinations do receive it:
+# TopicA and TopicB
+# TopicA and TopicC
+# Conditions for topics support two operators per expression, and parentheses are supported.
+# For more information, check: https://firebase.google.com/docs/cloud-messaging/topic-messaging
+```
+
+### Other argument options
+
+:
+
+    android_config (dict, optional): Android specific options for messages -
+        https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#androidconfig
+
+    apns_config (dict, optional): Apple Push Notification Service specific options -
+        https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#apnsconfig
+
+    webpush_config (dict, optional): Webpush protocol options -
+        https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#webpushconfig
+
+    fcm_options (dict, optional): Platform independent options for features provided by the FCM SDKs -
+        https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#fcmoptions
+
+    dry_run (bool, optional): If `True` no message will be sent but
+        request will be tested.