or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-operations.mdcore-messaging.mderror-handling.mdindex.md
tile.json

tessl/pypi-pyfcm

Python client for FCM - Firebase Cloud Messaging (Android, iOS and Web)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyfcm@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-pyfcm@2.1.0

index.mddocs/

PyFCM

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.

Package Information

  • Package Name: pyfcm
  • Language: Python
  • Installation: pip install pyfcm
  • Dependencies: requests, urllib3>=1.26.0, google-auth>=2.22.0, aiohttp>=3.8.6

Core Imports

from pyfcm import FCMNotification

Error handling:

from pyfcm.errors import (
    FCMError,
    AuthenticationError,
    FCMServerError,
    FCMNotRegisteredError,
    FCMSenderIdMismatchError,
    InvalidDataError,
    InternalPackageError,
    RetryAfterException
)

Package metadata:

from pyfcm import (
    __version__,
    __author__,
    __title__,
    __summary__,
    __url__,
    __email__,
    __license__
)

Basic Usage

from pyfcm import FCMNotification

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

# Send notification to a single device
result = fcm.notify(
    fcm_token="device_registration_token",
    notification_title="Hello World",
    notification_body="This is a test notification"
)

# Send data-only message
data_payload = {"key1": "value1", "key2": "value2"}
result = fcm.notify(
    fcm_token="device_registration_token",
    data_payload=data_payload
)

# Send to a topic
result = fcm.notify(
    topic_name="news",
    notification_title="Breaking News",
    notification_body="Important update"
)

Architecture

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

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

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

Capabilities

Core Messaging

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.

class FCMNotification:
    def __init__(
        self,
        service_account_file: Optional[str] = None,
        project_id: Optional[str] = None,
        credentials: Optional[Credentials] = None,
        proxy_dict: Optional[dict] = None,
        env: Optional[str] = None,
        json_encoder=None,
        adapter=None
    ):
        """Initialize FCM client"""

    def notify(
        self,
        fcm_token=None,
        notification_title=None,
        notification_body=None,
        notification_image=None,
        data_payload=None,
        topic_name=None,
        topic_condition=None,
        android_config=None,
        apns_config=None,
        webpush_config=None,
        fcm_options=None,
        dry_run=False,
        timeout=120
    ):
        """Send push notification"""

Core Messaging

Asynchronous Operations

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

def async_notify_multiple_devices(
    self,
    params_list: Optional[list] = None,
    timeout: int = 5
):
    """Send notifications to multiple devices asynchronously"""

Async Operations

Error Handling

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

class FCMError(Exception): ...
class AuthenticationError(FCMError): ...
class FCMServerError(FCMError): ...
class FCMNotRegisteredError(FCMError): ...
class FCMSenderIdMismatchError(FCMError): ...
class InvalidDataError(FCMError): ...
class InternalPackageError(FCMError): ...
class RetryAfterException(Exception): ...

Error Handling

Package Metadata

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

__version__: str  # Package version (e.g., "2.1.0")
__author__: str   # Package author
__title__: str    # Package title  
__summary__: str  # Package description
__url__: str      # Project URL
__email__: str    # Author email
__license__: str  # License type

Types

from typing import Optional
from google.oauth2.credentials import Credentials