tessl/pypi-gcloud
Python client library for Google Cloud Platform services including Datastore, Storage, and Pub/Sub
Overall
score
93%
datastore.mddocs/
Google Cloud Datastore
Google Cloud Datastore is a NoSQL document database service that provides automatic scaling, ACID transactions, and SQL-like queries. It stores data as entities with properties in a schemaless format.
Capabilities
Client Operations
High-level client for managing Datastore operations including entity CRUD, queries, transactions, and batch operations.
class Client:
def __init__(self, dataset_id=None, namespace=None, connection=None):
"""
Initialize Datastore client.
Parameters:
- dataset_id (str): Google Cloud project ID
- namespace (str): Optional namespace for entity isolation
- connection (Connection): Optional custom connection
"""
def get(self, key, missing=None, deferred=None):
"""
Retrieve entity by key.
Parameters:
- key (Key): Entity key to retrieve
- missing (list): Optional list to populate with missing keys
- deferred (list): Optional list to populate with deferred keys
Returns:
Entity or None if not found
"""
def get_multi(self, keys, missing=None, deferred=None):
"""
Retrieve multiple entities by keys.
Parameters:
- keys (list[Key]): List of entity keys
- missing (list): Optional list to populate with missing keys
- deferred (list): Optional list to populate with deferred keys
Returns:
list[Entity]: List of retrieved entities
"""
def put(self, entity):
"""
Save entity to datastore.
Parameters:
- entity (Entity): Entity to save
"""
def put_multi(self, entities):
"""
Save multiple entities to datastore.
Parameters:
- entities (list[Entity]): List of entities to save
"""
def delete(self, key):
"""
Delete entity by key.
Parameters:
- key (Key): Key of entity to delete
"""
def delete_multi(self, keys):
"""
Delete multiple entities by keys.
Parameters:
- keys (list[Key]): List of keys to delete
"""
def allocate_ids(self, incomplete_key, num_ids):
"""
Allocate unique IDs for incomplete keys.
Parameters:
- incomplete_key (Key): Partial key without ID
- num_ids (int): Number of IDs to allocate
Returns:
list[Key]: List of complete keys with allocated IDs
"""
def key(self, *path_args, **kwargs):
"""
Create Key instance.
Parameters:
- path_args: Alternating kind/id pairs for key path
- namespace (str): Optional namespace
- dataset_id (str): Optional dataset ID
Returns:
Key: New key instance
"""
def batch(self):
"""
Create batch context manager for grouping operations.
Returns:
Batch: Batch context manager
"""
def transaction(self):
"""
Create transaction context manager.
Returns:
Transaction: Transaction context manager
"""
def query(self, **kwargs):
"""
Create query instance.
Parameters:
- kind (str): Entity kind to query
- ancestor (Key): Optional ancestor filter
- filters (tuple): Property filters
- projection (tuple): Fields to return
- order (tuple): Sort order
- group_by (tuple): Group by fields
Returns:
Query: Query instance
"""Entity Management
Entities represent individual records in Datastore, extending Python dictionaries with key association and indexing control.
class Entity(dict):
def __init__(self, key=None, exclude_from_indexes=()):
"""
Initialize entity.
Parameters:
- key (Key): Optional associated key
- exclude_from_indexes (tuple): Property names to exclude from indexing
"""
@property
def key(self):
"""
Associated Key instance.
Returns:
Key or None
"""
@property
def kind(self):
"""
Entity kind derived from key.
Returns:
str or None
"""
@property
def exclude_from_indexes(self):
"""
Properties excluded from indexing.
Returns:
tuple: Property names
"""Key Management
Keys provide unique identification for Datastore entities, supporting hierarchical relationships and partial/complete states.
class Key:
def __init__(self, *path_args, **kwargs):
"""
Initialize key with path elements.
Parameters:
- path_args: Alternating kind/id pairs
- namespace (str): Optional namespace
- dataset_id (str): Optional dataset ID
"""
def completed_key(self, id_or_name):
"""
Create complete key from partial key.
Parameters:
- id_or_name (int|str): ID or name for final path element
Returns:
Key: Complete key
"""
def to_protobuf(self):
"""
Convert to protocol buffer representation.
Returns:
Protocol buffer key
"""
@property
def is_partial(self):
"""
Whether key lacks final ID/name.
Returns:
bool: True if incomplete
"""
@property
def namespace(self):
"""
Key namespace.
Returns:
str or None
"""
@property
def dataset_id(self):
"""
Dataset ID.
Returns:
str
"""
@property
def path(self):
"""
Full path as tuples.
Returns:
tuple: Path elements
"""
@property
def kind(self):
"""
Entity kind (final path element).
Returns:
str
"""
@property
def id(self):
"""
Entity numeric ID if any.
Returns:
int or None
"""
@property
def name(self):
"""
Entity string name if any.
Returns:
str or None
"""
@property
def parent(self):
"""
Parent key if any.
Returns:
Key or None
"""Query Operations
Query interface for searching and filtering entities with support for ordering, projection, and pagination.
class Query:
def __init__(self, client, kind=None, dataset_id=None, namespace=None,
ancestor=None, filters=(), projection=(), order=(), group_by=()):
"""
Initialize query.
Parameters:
- client (Client): Datastore client
- kind (str): Entity kind to query
- dataset_id (str): Optional dataset ID
- namespace (str): Optional namespace
- ancestor (Key): Optional ancestor filter
- filters (tuple): Property filters
- projection (tuple): Fields to return
- order (tuple): Sort order specifications
- group_by (tuple): Group by fields
"""
def add_filter(self, property_name, operator, value):
"""
Add property filter to query.
Parameters:
- property_name (str): Property to filter
- operator (str): Comparison operator ('=', '<', '<=', '>', '>=')
- value: Filter value
"""
def keys_only(self):
"""
Set projection to return only keys.
"""
def fetch(self, limit=None, offset=0, start_cursor=None, end_cursor=None, client=None):
"""
Execute query and return iterator.
Parameters:
- limit (int): Maximum results to return
- offset (int): Number of results to skip
- start_cursor (str): Starting cursor for pagination
- end_cursor (str): Ending cursor for pagination
- client (Client): Optional client override
Returns:
Iterator: Query result iterator
"""
@property
def kind(self):
"""
Entity kind being queried.
Returns:
str or None
"""
@property
def filters(self):
"""
Applied property filters.
Returns:
list: Filter specifications
"""Batch Operations
Batch operations group multiple datastore operations for efficient execution.
class Batch:
def __init__(self, client):
"""
Initialize batch with client.
Parameters:
- client (Client): Datastore client
"""
def put(self, entity):
"""
Add entity save to batch.
Parameters:
- entity (Entity): Entity to save
"""
def delete(self, key):
"""
Add key deletion to batch.
Parameters:
- key (Key): Key to delete
"""
def commit(self):
"""
Execute all batched operations.
"""
def __enter__(self):
"""
Enter context manager.
Returns:
Batch: Self
"""
def __exit__(self, exc_type, exc_val, exc_tb):
"""
Exit context manager and commit.
"""Transaction Operations
Transactions provide ACID guarantees for datastore operations with automatic retry and rollback support.
class Transaction(Batch):
def __init__(self, client):
"""
Initialize transaction.
Parameters:
- client (Client): Datastore client
"""
def begin(self):
"""
Start transaction.
"""
def commit(self):
"""
Commit transaction.
"""
def rollback(self):
"""
Rollback transaction.
"""
@property
def id(self):
"""
Transaction identifier.
Returns:
str: Transaction ID
"""Usage Examples
Basic Entity Operations
from gcloud import datastore
# Initialize client
client = datastore.Client(dataset_id='my-project')
# Create and save entity
key = client.key('Person', 'alice')
entity = datastore.Entity(key)
entity.update({
'name': 'Alice Smith',
'age': 30,
'email': 'alice@example.com'
})
client.put(entity)
# Retrieve entity
retrieved = client.get(key)
print(retrieved['name']) # Alice Smith
# Delete entity
client.delete(key)Query Operations
# Create query
query = client.query(kind='Person')
query.add_filter('age', '>=', 18)
query.add_filter('age', '<', 65)
# Execute query
results = list(query.fetch(limit=10))
for entity in results:
print(f"{entity['name']}: {entity['age']}")Batch Operations
# Batch multiple operations
with client.batch() as batch:
for i in range(5):
key = client.key('TestEntity', i)
entity = datastore.Entity(key)
entity['value'] = f'test-{i}'
batch.put(entity)Transaction Operations
# Atomic transaction
with client.transaction() as txn:
key = client.key('Counter', 'global')
counter = client.get(key)
if counter is None:
counter = datastore.Entity(key)
counter['count'] = 0
counter['count'] += 1
txn.put(counter)Install with Tessl CLI
npx tessl i tessl/pypi-gcloudevals
scenario-1
scenario-2
scenario-3
scenario-4
scenario-5
scenario-6
scenario-7
scenario-8
scenario-9
scenario-10