0
# PyFCM
1

2
Python client for Firebase Cloud Messaging (FCM) that enables sending push notifications to Android, iOS, and Web applications. PyFCM provides a comprehensive interface to Google's FCM HTTP v1 API with support for single device messaging, topic-based messaging, conditional messaging, and platform-specific configurations.
3

4
## Package Information
5

6
- **Package Name**: pyfcm
7
- **Language**: Python
8
- **Installation**: `pip install pyfcm`
9
- **Dependencies**: requests, urllib3>=1.26.0, google-auth>=2.22.0, aiohttp>=3.8.6
10

11
## Core Imports
12

13
```python
14
from pyfcm import FCMNotification
15
```
16

17
Error handling:
18

19
```python
20
from pyfcm.errors import (
21
    FCMError,
22
    AuthenticationError,
23
    FCMServerError,
24
    FCMNotRegisteredError,
25
    FCMSenderIdMismatchError,
26
    InvalidDataError,
27
    InternalPackageError,
28
    RetryAfterException
29
)
30
```
31

32
Package metadata:
33

34
```python
35
from pyfcm import (
36
    __version__,
37
    __author__,
38
    __title__,
39
    __summary__,
40
    __url__,
41
    __email__,
42
    __license__
43
)
44
```
45

46
## Basic Usage
47

48
```python
49
from pyfcm import FCMNotification
50

51
# Initialize with service account file
52
fcm = FCMNotification(
53
    service_account_file="path/to/service-account.json",
54
    project_id="your-project-id"
55
)
56

57
# Send notification to a single device
58
result = fcm.notify(
59
    fcm_token="device_registration_token",
60
    notification_title="Hello World",
61
    notification_body="This is a test notification"
62
)
63

64
# Send data-only message
65
data_payload = {"key1": "value1", "key2": "value2"}
66
result = fcm.notify(
67
    fcm_token="device_registration_token",
68
    data_payload=data_payload
69
)
70

71
# Send to a topic
72
result = fcm.notify(
73
    topic_name="news",
74
    notification_title="Breaking News",
75
    notification_body="Important update"
76
)
77
```
78

79
## Architecture
80

81
PyFCM is built around the FCMNotification class which inherits from BaseAPI. The architecture includes:
82

83
- **FCMNotification**: Main client class providing the notify() method
84
- **BaseAPI**: Core functionality including authentication, request handling, and payload parsing
85
- **Async Module**: Asynchronous operations for batch messaging
86
- **Error Classes**: Comprehensive exception handling for various FCM error conditions
87

88
The library handles OAuth2 authentication automatically, manages access token refresh, implements retry logic with exponential backoff, and provides thread-safe operations with connection pooling.
89

90
## Capabilities
91

92
### Core Messaging
93

94
Send push notifications to individual devices, topics, or conditional topic expressions. Supports notification messages, data messages, and combined message types with platform-specific configurations for Android, iOS, and Web.
95

96
```python { .api }
97
class FCMNotification:
98
    def __init__(
99
        self,
100
        service_account_file: Optional[str] = None,
101
        project_id: Optional[str] = None,
102
        credentials: Optional[Credentials] = None,
103
        proxy_dict: Optional[dict] = None,
104
        env: Optional[str] = None,
105
        json_encoder=None,
106
        adapter=None
107
    ):
108
        """Initialize FCM client"""
109

110
    def notify(
111
        self,
112
        fcm_token=None,
113
        notification_title=None,
114
        notification_body=None,
115
        notification_image=None,
116
        data_payload=None,
117
        topic_name=None,
118
        topic_condition=None,
119
        android_config=None,
120
        apns_config=None,
121
        webpush_config=None,
122
        fcm_options=None,
123
        dry_run=False,
124
        timeout=120
125
    ):
126
        """Send push notification"""
127
```
128

129
[Core Messaging](./core-messaging.md)
130

131
### Asynchronous Operations
132

133
Batch operations for sending notifications to multiple devices concurrently using asyncio and aiohttp for improved performance with large-scale messaging scenarios.
134

135
```python { .api }
136
def async_notify_multiple_devices(
137
    self,
138
    params_list: Optional[list] = None,
139
    timeout: int = 5
140
):
141
    """Send notifications to multiple devices asynchronously"""
142
```
143

144
[Async Operations](./async-operations.md)
145

146
### Error Handling
147

148
Comprehensive exception classes for different FCM error conditions including authentication errors, server errors, invalid tokens, and data validation failures.
149

150
```python { .api }
151
class FCMError(Exception): ...
152
class AuthenticationError(FCMError): ...
153
class FCMServerError(FCMError): ...
154
class FCMNotRegisteredError(FCMError): ...
155
class FCMSenderIdMismatchError(FCMError): ...
156
class InvalidDataError(FCMError): ...
157
class InternalPackageError(FCMError): ...
158
class RetryAfterException(Exception): ...
159
```
160

161
[Error Handling](./error-handling.md)
162

163
### Package Metadata
164

165
Access to package information and metadata constants for version checking and library identification.
166

167
```python { .api }
168
__version__: str  # Package version (e.g., "2.1.0")
169
__author__: str   # Package author
170
__title__: str    # Package title  
171
__summary__: str  # Package description
172
__url__: str      # Project URL
173
__email__: str    # Author email
174
__license__: str  # License type
175
```
176

177
## Types
178

179
```python { .api }
180
from typing import Optional
181
from google.oauth2.credentials import Credentials
182
```