Cloudflare Python Library

The Brand Protection API allows you to manage brand security through several sub-resources: submit, queries, matches, logos, and logo_matches.

• Submit: Use client.brand_protection.submit(account_id=...) to submit brand protection requests and client.brand_protection.url_info(account_id=...) to retrieve URL information.
• Queries: Manage brand protection queries using client.brand_protection.queries.create(...), delete(...), or bulk(...).
• Matches: Retrieve or download detected matches via client.brand_protection.matches.get(...) or client.brand_protection.matches.download(...).
• Logos: Manage brand logos with client.brand_protection.logos.create(...) and client.brand_protection.logos.delete(logo_id, account_id=...).
• LogoMatches: Access logo-specific matches using client.brand_protection.logo_matches.get(...) or client.brand_protection.logo_matches.download(...).

The cloudforceone.threatevents resource has undergone significant changes in v5. Key changes include the removal of insights and crons sub-resources, the deprecation of the get() method, and updates to create(), list(), edit(), and bulk_create() method signatures.

Summary of Changes

Required Actions

1. Replace insights calls: Move insight data into the insight parameter of the main threat events API.
2. Remove crons references: Use external scheduling mechanisms.
3. Update get() calls: Migrate to the dataset-specific endpoint: client.cloudforce_one.threat_events.datasets.events.get().
4. Update Type Hints: Change dataset_id type hints from List[str] to SequenceNotStr[str] in list() calls.

The import_() method uses overloaded signatures to manage a multi-step import process. You must provide an MD5 etag of your SQL file for all stages.

1. action="init": Initializes the import and returns an upload_url.
2. action="ingest": Triggers the ingestion after you have uploaded the file to the provided URL. Returns a bookmark.
3. action="poll": Uses the bookmark to check the status until it is complete.

import hashlib
import requests
import time

# Stage 1: Initialize
with open("database.sql", "rb") as f:
    etag = hashlib.md5(f.read()).hexdigest()

result = client.d1.database.import_(
    database_id="def456",
    account_id="abc123",
    action="init",
    etag=etag
)
upload_url = result.upload_url

# Stage 2: Upload and Ingest
with open("database.sql", "rb") as f:
    requests.put(upload_url, data=f)

result = client.d1.database.import_(
    database_id="def456",
    account_id="abc123",
    action="ingest",
    etag=etag,
    filename="database.sql"
)
bookmark = result.bookmark

# Stage 3: Poll for Completion
while True:
    status = client.d1.database.import_(
        database_id="def456",
        account_id="abc123",
        action="poll",
        current_bookmark=bookmark
    )
    if status.status == "complete":
        break
    time.sleep(5)

In v5, the SDK has transitioned from using NotGiven to using Omit for handling optional parameters in API calls. This provides better type safety and clearer semantics.

Actions Required:

1. Replace Imports: Change from cloudflare._types import NOT_GIVEN, NotGiven to from cloudflare._types import omit, Omit.
2. Replace Sentinel Values: Use omit instead of NOT_GIVEN when explicitly passing a parameter you wish to exclude.
3. Update Type Hints: Use Omit instead of NotGiven in function signatures.

Best Practice: Instead of explicitly passing omit, simply do not pass the optional parameter at all.

# Before (v4.3.1)
from cloudflare._types import NOT_GIVEN, NotGiven
result = client.queues.consumers.create(
    queue_id="abc123",
    account_id="def456",
    script_name="my-worker",
    dead_letter_queue=NOT_GIVEN
)

# After (v5)
from cloudflare._types import omit, Omit
result = client.queues.consumers.create(
    queue_id="abc123",
    account_id="def456",
    script_name="my-worker",
    dead_letter_queue=omit
)

# Preferred approach (v5)
result = client.queues.consumers.create(
    queue_id="abc123",
    account_id="def456",
    script_name="my-worker"
)

# After (v5)
from cloudflare._types import omit, Omit

result = client.queues.consumers.create(
    queue_id="abc123",
    account_id="def456",
    script_name="my-worker",
    dead_letter_queue=omit,
    settings=omit
)

In v5, the SDK replaced NotGiven and NOT_GIVEN with Omit and omit to handle optional parameters. This provides better type safety when distinguishing between an omitted parameter and an explicit None (null) value.

Actions:

1. Update Imports: Change from cloudflare._types import NOT_GIVEN, NotGiven to from cloudflare._types import omit, Omit.
2. Update Sentinel Values: Replace NOT_GIVEN with omit in method calls.
3. Update Type Hints: Use Omit in function signatures.

Best Practice: Instead of explicitly passing omit, simply omit the optional parameter from the function call entirely.

# Preferred approach: just omit the parameter
result = client.queues.consumers.create(
    queue_id="abc123",
    account_id="def456",
    script_name="my-worker"
)

# Explicit approach using omit
from cloudflare._types import omit
result = client.queues.consumers.create(
    queue_id="abc123",
    account_id="def456",
    script_name="my-worker",
    dead_letter_queue=omit
)