Storage Commands

Storage commands provide comprehensive browser storage management including cookies, localStorage, sessionStorage, and IndexedDB.

Overview

The storage commands module enables management of all browser storage mechanisms, providing functionality for data persistence and retrieval.

pydoll.commands.storage_commands

StorageCommands

A class for interacting with browser storage using Chrome DevTools Protocol (CDP).

The Storage domain of CDP allows managing various types of browser storage, including: - Cookies - Cache Storage - IndexedDB - Web Storage (localStorage/sessionStorage) - Shared Storage - Storage Buckets - Trust Tokens - Interest Groups - Attribution Reporting

This class provides static methods that generate CDP commands to manage these types of storage without the need for traditional webdrivers.

clear_cookies `staticmethod`

clear_cookies(browser_context_id=None)

Generates a command to clear all browser cookies.

PARAMETER	DESCRIPTION
`browser_context_id`	Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs). TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to clear all cookies. TYPE: `Command[Response]`

clear_data_for_origin `staticmethod`

clear_data_for_origin(origin, storage_types)

Generates a command to clear storage data for a specific origin.

PARAMETER	DESCRIPTION
`origin`	The security origin (e.g., "https://example.com"). TYPE: `str`
`storage_types`	Comma-separated list of storage types to clear. Possible values include: "cookies", "local_storage", "indexeddb", "cache_storage", etc. Use "all" to clear all types. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to clear data for the specified origin. TYPE: `Command[Response]`

clear_data_for_storage_key `staticmethod`

clear_data_for_storage_key(storage_key, storage_types)

Generates a command to clear data for a specific storage key.

PARAMETER	DESCRIPTION
`storage_key`	The storage key for which to clear data. Unlike origin, a storage key is a more specific identifier that may include partition isolation. TYPE: `str`
`storage_types`	Comma-separated list of storage types to clear. Possible values include: "cookies", "local_storage", "indexeddb", "cache_storage", etc. Use "all" to clear all types. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to clear data for the specified storage key. TYPE: `Command[Response]`

get_cookies `staticmethod`

get_cookies(browser_context_id=None)

Generates a command to get all browser cookies.

PARAMETER	DESCRIPTION
`browser_context_id`	Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs). TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to get all cookies, which will return an array of Cookie objects. TYPE: `Command[GetCookiesResponse]`

get_storage_key_for_frame `staticmethod`

get_storage_key_for_frame(frame_id)

Generates a command to get the storage key for a specific frame.

Storage keys are used to isolate data between different origins or partitions in the browser.

PARAMETER	DESCRIPTION
`frame_id`	The ID of the frame for which to get the storage key. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to get the storage key for the specified frame. TYPE: `Command[GetStorageKeyForFrameResponse]`

get_usage_and_quota `staticmethod`

get_usage_and_quota(origin)

Generates a command to get storage usage and quota information for an origin.

Useful for monitoring or debugging storage consumption of a site.

PARAMETER	DESCRIPTION
`origin`	The security origin (e.g., "https://example.com") for which to get information. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command that will return: - usage: Storage usage in bytes - quota: Storage quota in bytes - usageBreakdown: Breakdown of usage by storage type - overrideActive: Whether there is an active quota override TYPE: `Command[GetUsageAndQuotaResponse]`

set_cookies `staticmethod`

set_cookies(cookies, browser_context_id=None)

Generates a command to set browser cookies.

PARAMETER	DESCRIPTION
`cookies`	list of Cookie objects to set. TYPE: `list[CookieParam]`
`browser_context_id`	Browser context ID (optional). Useful when working with multiple contexts (e.g., multiple windows or tabs). TYPE: `Optional[str]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to set the specified cookies. TYPE: `Command[Response]`

set_protected_audience_k_anonymity `staticmethod`

set_protected_audience_k_anonymity(owner, name, hashes)

Generates a command to set K-anonymity for protected audience.

This command is used to configure anonymity in privacy-preserving advertising systems (part of Google's Privacy Sandbox).

PARAMETER	DESCRIPTION
`owner`	Owner of the K-anonymity configuration. TYPE: `str`
`name`	Name of the K-anonymity configuration. TYPE: `str`
`hashes`	list of hashes for the configuration. TYPE: `list[str]`

RETURNS	DESCRIPTION
`Command`	The CDP command to set protected audience K-anonymity. TYPE: `Command[Response]`

track_cache_storage_for_origin `staticmethod`

track_cache_storage_for_origin(origin)

Generates a command to register an origin to receive notifications about changes to its Cache Storage.

Cache Storage is primarily used by Service Workers to store resources for offline use.

PARAMETER	DESCRIPTION
`origin`	The security origin (e.g., "https://example.com") to monitor. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to register monitoring of the origin's Cache Storage. TYPE: `Command[Response]`

track_cache_storage_for_storage_key `staticmethod`

track_cache_storage_for_storage_key(storage_key)

Generates a command to register a storage key to receive notifications about changes to its Cache Storage.

Similar to track_cache_storage_for_origin, but uses the storage key for more precise isolation.

PARAMETER	DESCRIPTION
`storage_key`	The storage key to monitor. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to register monitoring of the key's Cache Storage. TYPE: `Command[Response]`

track_indexed_db_for_origin `staticmethod`

track_indexed_db_for_origin(origin)

Generates a command to register an origin to receive notifications about changes to its IndexedDB.

IndexedDB is a NoSQL database system in the browser for storing large amounts of structured data.

PARAMETER	DESCRIPTION
`origin`	The security origin (e.g., "https://example.com") to monitor. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to register monitoring of the origin's IndexedDB. TYPE: `Command[Response]`

track_indexed_db_for_storage_key `staticmethod`

track_indexed_db_for_storage_key(storage_key)

Generates a command to register a storage key to receive notifications about changes to its IndexedDB.

Similar to track_indexed_db_for_origin, but uses the storage key for more precise isolation.

PARAMETER	DESCRIPTION
`storage_key`	The storage key to monitor. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to register monitoring of the key's IndexedDB. TYPE: `Command[Response]`

untrack_cache_storage_for_origin `staticmethod`

untrack_cache_storage_for_origin(origin)

Generates a command to unregister an origin from receiving notifications about changes to its Cache Storage.

Use this method to stop monitoring Cache Storage after using track_cache_storage_for_origin.

PARAMETER	DESCRIPTION
`origin`	The security origin (e.g., "https://example.com") to stop monitoring. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to cancel monitoring of the origin's Cache Storage. TYPE: `Command[Response]`

untrack_cache_storage_for_storage_key `staticmethod`

untrack_cache_storage_for_storage_key(storage_key)

Generates a command to unregister a storage key from receiving notifications about changes to its Cache Storage.

Use this method to stop monitoring Cache Storage after using track_cache_storage_for_storage_key.

PARAMETER	DESCRIPTION
`storage_key`	The storage key to stop monitoring. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to cancel monitoring of the key's Cache Storage. TYPE: `Command[Response]`

untrack_indexed_db_for_origin `staticmethod`

untrack_indexed_db_for_origin(origin)

Generates a command to unregister an origin from receiving notifications about changes to its IndexedDB.

Use this method to stop monitoring IndexedDB after using track_indexed_db_for_origin.

PARAMETER	DESCRIPTION
`origin`	The security origin (e.g., "https://example.com") to stop monitoring. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to cancel monitoring of the origin's IndexedDB. TYPE: `Command[Response]`

untrack_indexed_db_for_storage_key `staticmethod`

untrack_indexed_db_for_storage_key(storage_key)

Generates a command to unregister a storage key from receiving notifications about changes to its IndexedDB.

Use this method to stop monitoring IndexedDB after using track_indexed_db_for_storage_key.

PARAMETER	DESCRIPTION
`storage_key`	The storage key to stop monitoring. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to cancel monitoring of the key's IndexedDB. TYPE: `Command[Response]`

clear_shared_storage_entries `staticmethod`

clear_shared_storage_entries(owner_origin)

Generates a command to clear all Shared Storage entries for a specific origin.

Shared Storage is an experimental API that allows cross-origin shared storage with privacy protections.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the Shared Storage to clear. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to clear the Shared Storage entries. TYPE: `Command[Response]`

clear_trust_tokens `staticmethod`

clear_trust_tokens(issuer_origin)

Generates a command to remove all Trust Tokens issued by the specified origin.

Trust Tokens are an experimental API for combating fraud while preserving user privacy. This command keeps other stored data, including the issuer's redemption records, intact.

PARAMETER	DESCRIPTION
`issuer_origin`	The issuer origin of the tokens to remove. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to clear Trust Tokens, which will return: - didDeleteTokens: True if any tokens were deleted, False otherwise. TYPE: `Command[ClearTrustTokensResponse]`

delete_shared_storage_entry `staticmethod`

delete_shared_storage_entry(owner_origin, key)

Generates a command to delete a specific Shared Storage entry.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the Shared Storage. TYPE: `str`
`key`	The key of the entry to delete. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to delete the Shared Storage entry. TYPE: `Command[Response]`

delete_storage_bucket `staticmethod`

delete_storage_bucket(bucket)

Generates a command to delete a Storage Bucket with the specified key and name.

Storage Buckets are an experimental API for managing storage data with greater granularity and expiration control.

PARAMETER	DESCRIPTION
`bucket`	A StorageBucket object containing the storageKey and name of the bucket to delete. TYPE: `StorageBucket`

RETURNS	DESCRIPTION
`Command`	The CDP command to delete the Storage Bucket. TYPE: `Command[Response]`

get_affected_urls_for_third_party_cookie_metadata `staticmethod`

get_affected_urls_for_third_party_cookie_metadata(first_party_url, third_party_urls)

Generates a command to get the list of URLs from a page and its embedded resources that match existing grace period URL pattern rules.

This command is useful for monitoring which URLs would be affected by the Privacy Sandbox's third-party cookie policies.

PARAMETER	DESCRIPTION
`first_party_url`	The URL of the page being visited (first-party). TYPE: `str`
`third_party_urls`	Optional list of embedded third-party resource URLs. TYPE: `list[str]`

RETURNS	DESCRIPTION
`Command`	The CDP command to get URLs affected by third-party cookie metadata. TYPE: `Command[GetAffectedUrlsForThirdPartyCookieMetadataResponse]`

get_interest_group_details `staticmethod`

get_interest_group_details(owner_origin, name)

Generates a command to get details of a specific interest group.

Interest Groups are part of the FLEDGE/Protected Audience API for privacy-preserving advertising, enabling in-browser ad auctions.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the interest group. TYPE: `str`
`name`	The name of the interest group. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to get interest group details. TYPE: `Command[GetInterestGroupDetailsResponse]`

get_related_website_sets `staticmethod`

get_related_website_sets(sets)

Generates a command to get related website sets.

Related Website Sets are an API that allows sites under the same entity to share some data, despite third-party cookie restrictions.

PARAMETER	DESCRIPTION
`sets`	list of RelatedWebsiteSet objects. TYPE: `list[RelatedWebsiteSet]`

RETURNS	DESCRIPTION
`Command`	The CDP command to get related website sets. TYPE: `Command[GetRelatedWebsiteSetsResponse]`

get_shared_storage_entries `staticmethod`

get_shared_storage_entries(owner_origin)

Generates a command to get all Shared Storage entries for an origin.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the Shared Storage. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to get the Shared Storage entries. TYPE: `Command[GetSharedStorageEntriesResponse]`

get_shared_storage_metadata `staticmethod`

get_shared_storage_metadata(owner_origin)

Generates a command to get Shared Storage metadata for an origin.

Metadata includes information such as usage, budget, and creation time.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the Shared Storage. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to get Shared Storage metadata. TYPE: `Command[GetSharedStorageMetadataResponse]`

get_trust_tokens `staticmethod`

get_trust_tokens()

Generates a command to get all available Trust Tokens.

RETURNS	DESCRIPTION
`Command`	The CDP command to get Trust Tokens, which will return pairs of issuer origin and count of available tokens. TYPE: `Command[GetTrustTokensResponse]`

override_quota_for_origin `staticmethod`

override_quota_for_origin(origin, quota_size=None)

Generates a command to override the storage quota for a specific origin.

This command is useful for storage exhaustion testing or simulating different storage conditions.

PARAMETER	DESCRIPTION
`origin`	The origin for which to override the quota. TYPE: `str`
`quota_size`	The size of the new quota in bytes (optional). If not specified, any existing override will be removed. TYPE: `Optional[float]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to override the origin's quota. TYPE: `Command[Response]`

reset_shared_storage_budget `staticmethod`

reset_shared_storage_budget(owner_origin)

Generates a command to reset the Shared Storage budget for an origin.

Shared Storage uses a budget system to limit the amount of operations or specific operations to preserve user privacy.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the Shared Storage. TYPE: `str`

RETURNS	DESCRIPTION
`Command`	The CDP command to reset the Shared Storage budget. TYPE: `Command[Response]`

run_bounce_tracking_mitigations `staticmethod`

run_bounce_tracking_mitigations()

Generates a command to run bounce tracking mitigations.

Bounce tracking is a tracking technique that involves redirecting users through intermediate URLs to establish tracking cookies. This command activates protections against this technique.

RETURNS	DESCRIPTION
`Command`	The CDP command to run bounce tracking mitigations. TYPE: `Command[RunBounceTrackingMitigationsResponse]`

send_pending_attribution_reports `staticmethod`

send_pending_attribution_reports()

Generates a command to send pending attribution reports.

Attribution Reporting is an API that allows measuring conversions while preserving user privacy. This command forces sending reports that are waiting to be sent.

RETURNS	DESCRIPTION
`Command`	The CDP command to send pending attribution reports. TYPE: `Command[SendPendingAttributionReportsResponse]`

set_attribution_reporting_local_testing_mode `staticmethod`

set_attribution_reporting_local_testing_mode(enable)

Generates a command to enable or disable local testing mode for Attribution Reporting.

Testing mode makes it easier to develop and test the Attribution Reporting API by removing restrictions like delays and rate limits that would normally apply.

PARAMETER	DESCRIPTION
`enable`	True to enable local testing mode, False to disable it. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	The CDP command to set Attribution Reporting local testing mode. TYPE: `Command[Response]`

set_attribution_reporting_tracking `staticmethod`

set_attribution_reporting_tracking(enable)

Generates a command to enable or disable Attribution Reporting tracking.

PARAMETER	DESCRIPTION
`enable`	True to enable tracking, False to disable it. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	The CDP command to set Attribution Reporting tracking. TYPE: `Command[Response]`

set_interest_group_auction_tracking `staticmethod`

set_interest_group_auction_tracking(enable)

Generates a command to enable or disable interest group auction tracking.

Interest group auctions are part of the FLEDGE/Protected Audience API and allow for in-browser ad auctions in a privacy-preserving way.

PARAMETER	DESCRIPTION
`enable`	True to enable tracking, False to disable it. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	The CDP command to set interest group auction tracking. TYPE: `Command[Response]`

set_interest_group_tracking `staticmethod`

set_interest_group_tracking(enable)

Generates a command to enable or disable interest group tracking.

PARAMETER	DESCRIPTION
`enable`	True to enable tracking, False to disable it. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	The CDP command to set interest group tracking. TYPE: `Command[Response]`

set_shared_storage_entry `staticmethod`

set_shared_storage_entry(owner_origin, key, value, ignore_if_present=None)

Generates a command to set an entry in Shared Storage.

PARAMETER	DESCRIPTION
`owner_origin`	The owner origin of the Shared Storage. TYPE: `str`
`key`	The key of the entry to set. TYPE: `str`
`value`	The value of the entry to set. TYPE: `str`
`ignore_if_present`	If True, won't replace an existing entry with the same key. TYPE: `Optional[bool]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Command`	The CDP command to set a Shared Storage entry. TYPE: `Command[Response]`

set_shared_storage_tracking `staticmethod`

set_shared_storage_tracking(enable)

Generates a command to enable or disable Shared Storage tracking.

When enabled, events related to Shared Storage usage will be emitted.

PARAMETER	DESCRIPTION
`enable`	True to enable tracking, False to disable it. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	The CDP command to set Shared Storage tracking. TYPE: `Command[Response]`

set_storage_bucket_tracking `staticmethod`

set_storage_bucket_tracking(storage_key, enable)

Generates a command to enable or disable Storage Bucket tracking.

When enabled, events related to changes in storage buckets will be emitted.

PARAMETER	DESCRIPTION
`storage_key`	The storage key for which to set tracking. TYPE: `str`
`enable`	True to enable tracking, False to disable it. TYPE: `bool`

RETURNS	DESCRIPTION
`Command`	The CDP command to set Storage Bucket tracking. TYPE: `Command[Response]`

Usage

Storage commands are used for managing browser storage across different mechanisms:

from pydoll.commands.storage_commands import get_cookies, set_cookies, clear_data_for_origin
from pydoll.connection.connection_handler import ConnectionHandler

# Get cookies for a domain
connection = ConnectionHandler()
cookies = await get_cookies(connection, urls=["https://example.com"])

# Set a new cookie
await set_cookies(connection, cookies=[{
    "name": "session_id",
    "value": "abc123",
    "domain": "example.com",
    "path": "/",
    "httpOnly": True,
    "secure": True
}])

# Clear all storage for an origin
await clear_data_for_origin(
    connection,
    origin="https://example.com",
    storage_types="all"
)

Key Functionality

The storage commands module provides functions for:

get_cookies() - Get cookies by URL or domain
set_cookies() - Set new cookies
delete_cookies() - Delete specific cookies
clear_cookies() - Clear all cookies

Local Storage

get_dom_storage_items() - Get localStorage items
set_dom_storage_item() - Set localStorage item
remove_dom_storage_item() - Remove localStorage item
clear_dom_storage() - Clear localStorage

Session Storage

Session storage operations (similar to localStorage)
Session-specific data management
Tab-isolated storage

IndexedDB

get_database_names() - Get IndexedDB databases
request_database() - Access database structure
request_data() - Query database data
clear_object_store() - Clear object stores

Cache Storage

request_cache_names() - Get cache names
request_cached_response() - Get cached responses
delete_cache() - Delete cache entries

Application Cache (Deprecated)

Legacy application cache support
Manifest-based caching

Advanced Features

Bulk Operations

# Clear all storage types for multiple origins
origins = ["https://example.com", "https://api.example.com"]
for origin in origins:
    await clear_data_for_origin(
        connection,
        origin=origin,
        storage_types="cookies,local_storage,session_storage,indexeddb"
    )

Storage Quotas

# Get storage quota information
quota_info = await get_usage_and_quota(connection, origin="https://example.com")
print(f"Used: {quota_info.usage} bytes")
print(f"Quota: {quota_info.quota} bytes")

Cross-Origin Storage

# Manage storage across different origins
await set_cookies(connection, cookies=[{
    "name": "cross_site_token",
    "value": "token123",
    "domain": ".example.com",  # Applies to all subdomains
    "sameSite": "None",
    "secure": True
}])

Storage Types

The module supports various storage mechanisms:

Storage Type	Persistence	Scope	Capacity
Cookies	Persistent	Domain/Path	~4KB per cookie
localStorage	Persistent	Origin	~5-10MB
sessionStorage	Session	Tab	~5-10MB
IndexedDB	Persistent	Origin	Large (GB+)
Cache API	Persistent	Origin	Large

Privacy Considerations

Storage operations can affect user privacy. Always handle storage data responsibly and in compliance with privacy regulations.

Storage Commands

Overview

pydoll.commands.storage_commands

StorageCommands

clear_cookies staticmethod

clear_data_for_origin staticmethod

clear_data_for_storage_key staticmethod

get_cookies staticmethod

get_storage_key_for_frame staticmethod

get_usage_and_quota staticmethod

set_cookies staticmethod

set_protected_audience_k_anonymity staticmethod

track_cache_storage_for_origin staticmethod

track_cache_storage_for_storage_key staticmethod

track_indexed_db_for_origin staticmethod

track_indexed_db_for_storage_key staticmethod

untrack_cache_storage_for_origin staticmethod

untrack_cache_storage_for_storage_key staticmethod

untrack_indexed_db_for_origin staticmethod

untrack_indexed_db_for_storage_key staticmethod

clear_shared_storage_entries staticmethod

clear_trust_tokens staticmethod

delete_shared_storage_entry staticmethod

delete_storage_bucket staticmethod

get_affected_urls_for_third_party_cookie_metadata staticmethod

get_interest_group_details staticmethod

get_related_website_sets staticmethod

get_shared_storage_entries staticmethod

get_shared_storage_metadata staticmethod

get_trust_tokens staticmethod

override_quota_for_origin staticmethod

reset_shared_storage_budget staticmethod

run_bounce_tracking_mitigations staticmethod

send_pending_attribution_reports staticmethod

set_attribution_reporting_local_testing_mode staticmethod

set_attribution_reporting_tracking staticmethod

set_interest_group_auction_tracking staticmethod

set_interest_group_tracking staticmethod

set_shared_storage_entry staticmethod

set_shared_storage_tracking staticmethod

set_storage_bucket_tracking staticmethod