AZURECOS...FORPYTHON(1)

📦
version 1.0.5+git20191025 · 2 versions
, in debian bookworm, ubuntu noble

💖 AZURECOS...FORPYTHON 💖 — the AZURECOS...FORPYTHON(1) manual, Azure CosmosDB SDK for Python edition 🦋

okay bestie, sit down, hydrate, because this is the Azure CosmosDB SDK for Python page and it's a whole journey. no cap. ✨

🎀 NAME 🎀

azurecosmosdbsdkforpython — Azure CosmosDB SDK for Python 1.0.6 💅

🌸 INSTALLATION: 🌸

pls pls pls go look at the Github page for the installation instructions, they live there, not here:

https://github.com/Azure/azure-cosmosdb-python

and hiii, if you're actually hunting for Azure Service Bus or the Azure management libraries (different vibes, different repo), the address is:

https://github.com/Azure/azure-sdk-for-python

✨ DOCUMENTATION: ✨

the receipts, all lined up:

  • Table Getting Started Doc — (API) 🫶
  • Reference Documentation - All Services 👑

🔥 FEATURES: 🔥

  • Table
    • Create/Read/Update/Delete Tables 🎀
    • Create/Read/Update/Delete Entities 💖
    • Batch operations ⚡
    • Advanced Table Operations 👑

💀 SYSTEM REQUIREMENTS: 💀

the Python versions that are invited to the party: 2.7.x, 3.3.x, 3.4.x, and 3.5.x. to download Python, go here:

https://www.python.org/download/

also, lowkey a rec: we recommend Python Tools for Visual Studio as your dev environment for building your apps. more info right here:

http://aka.ms/python

😭 NEED HELP?: 😭

if the provided code is giving you grief, bestie, pls check out the Microsoft Azure Developer Forums on Stack Overflow. that's where the help is. fr fr.

🌈 CONTRIBUTING: 🌈

💜 Contribute Code or Provide Feedback: 💜

if you wanna be an active contributor to this project (main character energy, honestly), just follow the instructions in the Microsoft Azure Projects Contribution Guidelines. ✨

and if you bump into any bugs in the library — no stress, it happens — pls file an issue in the Issues section of the project. 🐛

Microsoft Azure Python Developer Center

  • Index 📑
  • Module Index 📚
  • Search Page 🔍

🦋 UPGRADE GUIDE 🦋

okay so this guide exists to help you upgrade code you wrote for the Azure Storage Python library before version 0.30.0. yes, before. ancient times. 🙈

the best way to see how to upgrade any specific API is to peek at the usage samples in the Samples directory on GitHub. and if you want the very specific set of changes plus the additions, they're all in the ChangeLog and BreakingChanges documents. what's below is just the summary of those docs, holding the most relevant pieces for the upgrade scenario. 💅

⭐ GENERAL CHANGES ⭐

so generally speaking, we tried to use more appropriate Python types for parameters and return values instead of always taking and receiving strings. iconic behaviour, honestly.

parameter and return values that used to be prefixed with x_ms got simplified by yeeting that prefix, and parameter values are divided by '_' between words, as is idiomatic. ✨

listing now returns a generator rather than a result segment. and this generator automatically follows continuation tokens as more results are requested. obsessed.

SAS methods take several individual parameters rather than a single paramter object. (spelling is theirs, we're keeping it. 💀) similarly, ACL getters and setters take dictionaries mapping id to AccessPolicy rather than a list of SignedIdentifiers each holding an id and an AccessPolicy.

🎀 BLOB 🎀

the single BlobService object got divided into three subservices for the different blob types — BlockBlobService, PageBlobService, AppendBlobService — with common methods living in the abstract BaseBlobService that these inherit from. why? two reasons, bestie:

  1. to reduce confusion when blob-type specific methods were used on the incorrect blob type. 🙈
  2. to simplify the BlobService object, which had grown to be quite extensive when append blob was added. 😮‍💨

ContentSettings objects have replaced all content_* and cache_control parameters and return values for applicable APIs. this is meant to highlight that the semantics of setting content properties is replace rather than merge — meaning that setting any one property will cause any unspecified properties to be cleared on the blob. ⚠️ important!!

on the performance side: single-threaded blob download APIs will now download the blob without chunking to improve perf, and they won't do an initial get to find the size of the blob. BUT — as a result — the progress_callback may receive None for its total parameter when parallelism is off, to allow for this optimization. 💅

🌸 QUEUE 🌸

the largest change to the QueueService class is that queue messages are both XML encoded and decoded by default. in past versions, either messages were not encoded or decoded by default, or only encoded. if you wanna change that, encoding and decoding methods can be modified using the QueueService encode_function and decode_function instance variables. 🔧

methods operating on queue messages and which have return values will return QueueMessage objects. QueueMessages objects contain essentially the same fields as previously, but the times are returned as dates rather than strings, and the dequeue count is returned as an int. periodt.

💖 TABLE 💖

instead of having a boolean switch for turning batching on and off, batches are now an object which can be populated and then committed. ✨

entities can be sent as dictionaries or as Entity objects, and returned entities are accessible as either objects or dictionaries. methods which access and modify entites (their spelling, again, keeping it 🫶) have been simplified so that if they take an entity object, they extract the partition key and row key from that object rather than requiring these be sent separately.

all table entity integer values are stored on the service with type Edm.Int64 unless the type is explicitly overridden as Edm.Int32. formerly, the type was decided based on the size of the number, but this resulted in hard to predict types on the service. so, the more consistent option was chosen. the way that's just good design. 👑

operations no longer echo content from the service, and JSON is used instead of AtomPub, improving performance. 🔥

🌈 AZURE PACKAGE 🌈

Subpackages

💜 azure.cosmosdb package 💜

Subpackages

✨ azure.cosmosdb.table package ✨

Submodules

🦋 azure.cosmosdb.table.models module 🦋

  • exception azure.cosmosdb.table.models.AzureBatchOperationError(message, status_code, *args, **kwargs) — Bases: azure.common.AzureHttpError

Indicates that a batch operation failed. 😭

Variables

  • message (str) — a detailed error message indicating the index of the batch request which failed and the reason for the failure. for example, '0:One of the request inputs is out of range.' indicates the 0th batch request failed as one of its property values was out of range. 💀
  • status_code (int) — the HTTP status code of the batch request. for example, 400.
  • batch_code (str) — the batch status code. for example, 'OutOfRangeInput'.
  • exception azure.cosmosdb.table.models.AzureBatchValidationError — Bases: azure.common.AzureException

Indicates that a batch operation cannot proceed due to invalid input. 🚫

Variables

  • message (str) — a detailed error message indicating the reason for the failure.
  • class azure.cosmosdb.table.models.EdmType — Bases: object

Used by EntityProperty to represent the type of the entity property to be stored by the Table service. ✨

  • BINARY = 'Edm.Binary' — represents byte data. Must be specified.
  • BOOLEAN = 'Edm.Boolean' — represents a boolean. this type will be inferred for Python bools.
  • DATETIME = 'Edm.DateTime' — represents a date. this type will be inferred for Python datetime objects.
  • DOUBLE = 'Edm.Double' — represents a double. this type will be inferred for Python floating point numbers.
  • GUID = 'Edm.Guid' — represents a GUID. Must be specified.
  • INT32 = 'Edm.Int32' — represents a number between -(2^15) and 2^15. Must be specified or numbers will default to INT64.
  • INT64 = 'Edm.Int64' — represents a number between -(2^31) and 2^31. this is the default type for Python numbers.
  • STRING = 'Edm.String' — represents a string. this type will be inferred for Python strings.
  • class azure.cosmosdb.table.models.Entity — Bases: dict

an entity object. can be accessed as a dict or as an obj. the attributes of the entity will be created dynamically. for example, both of these are valid, no cap:

entity = Entity()
entity.a = 'b'
entity['x'] = 'y'
  • class azure.cosmosdb.table.models.EntityProperty(type=None, value=None, encrypt=False) — Bases: object

an entity property. used to explicitly set EdmType when necessary. 💅

values which require explicit typing are GUID, INT32, and BINARY. other EdmTypes may be explicitly create as EntityProperty objects but need not be. for example, the below with both create STRING typed properties on the entity:

entity = Entity()
entity.a = 'b'
entity.x = EntityProperty(EdmType.STRING, 'y')

Represents an Azure Table. Returned by list_tables.

Parameters

  • type (str) — the type of the property.
  • value (EdmType) — the value of the property.
  • encrypt (bool) — indicates whether or not the property should be encrypted. 🔐
  • class azure.cosmosdb.table.models.Table — Bases: object

Represents an Azure Table. Returned by list_tables. 🎀

Variables

  • name (str) — the name of the table.
  • class azure.cosmosdb.table.models.TablePayloadFormat — Bases: object

specifies the accepted content type of the response payload. more information can be found here: https://msdn.microsoft.com/en-us/library/azure/dn535600.aspx 🌐

  • JSON_FULL_METADATA = 'application/json;odata=fullmetadata' — returns minimal type information for the entity properties plus some extra odata properties.
  • JSON_MINIMAL_METADATA = 'application/json;odata=minimalmetadata' — returns minimal type information for the entity properties.
  • JSON_NO_METADATA = 'application/json;odata=nometadata' — returns no type information for the entity properties.
  • class azure.cosmosdb.table.models.TablePermissions(query=False, add=False, update=False, delete=False, _str=None) — Bases: object

TablePermissions class to be used with the generate_table_shared_access_signature() method and for the AccessPolicies used with set_table_acl(). 🔑

Variables

  • TablePermissions.QUERY (TablePermissions) — get entities and query entities.
  • TablePermissions.ADD (TablePermissions) — add entities.
  • TablePermissions.UPDATE (TablePermissions) — update entities.
  • TablePermissions.DELETE (TablePermissions) — delete entities.

Parameters

okay wait, that's where part 1 runs out — the Parameters list is still going, so hold that thought bestie, part 2 is right there 💜

  • query (bool) — lets you get entities and query entities. the whole little buffet 💅
    • add (bool) — add entities. btw if you're doing an upsert, you need Add AND Update permissions, both of them, no skipping 🫶
    • update (bool) — update entities. same deal: upserts need Add and Update together.
    • delete (bool) — delete entities. bye bye bestie 💀
    • _str (str) — a string that represents the permissions. it's giving "permissions but make it text" ✨
ADD = <azure.cosmosdb.table.models.TablePermissions object>

DELETE = <azure.cosmosdb.table.models.TablePermissions object>

QUERY = <azure.cosmosdb.table.models.TablePermissions object>

UPDATE = <azure.cosmosdb.table.models.TablePermissions object>

✨ class azure.cosmosdb.table.models.TableServices

Bases: azure.cosmosdb.table.common.models.Services

so this one is the services version of the same vibe, here's what it takes:

Parameters

  • table (bool) — access to the .TableService 👑
  • _str (str) — a string representing the services.

🌸 azure.cosmosdb.table.tablebatch module

💖 class azure.cosmosdb.table.tablebatch.TableBatch(require_encryption=False, key_encryption_key=None, encryption_resolver=None)

Bases: object

okay bestie this is the class for batch operations on the storage table service, and it's lowkey the moment 🎀

so here's the tea: the Table service does batch transactions on entities that live in the same table and belong to the same partition group. you can stack multiple operations into a single transaction. but — and this is the important part — the batch can include at most 100 entities, and its total payload may be no more than 4 MB in size. that's the ceiling, don't fight it 🙈

delete_entity(partition_key, row_key, if_match='*')

adds a delete entity operation to the batch. peep delete_entity() for more info on deletes.

⚠️ the operation will not be executed until the batch is committed. it just sits there, waiting, like a text you haven't sent yet 😭

Parameters

  • partition_key (str) — the PartitionKey of the entity.
  • row_key (str) — the RowKey of the entity.
  • if_match (str) — you (the client) can specify the ETag for the entity on the request so it gets compared against the ETag the service is holding onto, all for the sake of optimistic concurrency. the delete only goes through if the ETag you sent matches what the server has, which means nobody touched the entity since you grabbed it. wanna force an unconditional delete? set If-Match to the wildcard character (*). periodt.

insert_entity(entity)

adds an insert entity operation to the batch. see insert_entity() for more info on inserts.

⚠️ same rule: not executed until the batch is committed.

Parameters

  • entity (dict or Entity) — the entity to insert. could be a dict or an entity object. must contain a PartitionKey and a RowKey.

insert_or_merge_entity(entity)

adds an insert or merge entity operation to the batch. see insert_or_merge_entity() for more info on insert or merge operations.

⚠️ you already know: not executed until the batch is committed.

Parameters

  • entity (dict or Entity) — the entity to insert or merge. could be a dict or an entity object. must contain a PartitionKey and a RowKey.

insert_or_replace_entity(entity)

adds an insert or replace entity operation to the batch. see insert_or_replace_entity() for more info on insert or replace operations.

⚠️ say it with me: not executed until the batch is committed.

Parameters

  • entity (dict or Entity) — the entity to insert or replace. could be a dict or an entity object. must contain a PartitionKey and a RowKey.

merge_entity(entity, if_match='*')

adds a merge entity operation to the batch. see merge_entity() for more info on merges.

⚠️ not executed until the batch is committed, bestie.

Parameters

  • entity (dict or Entity) — the entity to merge. could be a dict or an entity object. must contain a PartitionKey and a RowKey.
  • if_match (str) — the client can specify the ETag for the entity on the request so it's compared to the ETag the service maintains, for optimistic concurrency reasons. the merge only happens if the ETag you sent matches the server's value, meaning the entity hasn't been modified since you retrieved it. to force an unconditional merge, set If-Match to the wildcard character (*). slay.

update_entity(entity, if_match='*')

adds an update entity operation to the batch. see update_entity() for more info on updates.

⚠️ you guessed it — not executed until the batch is committed.

Parameters

  • entity (dict or Entity) — the entity to update. could be a dict or an entity object. must contain a PartitionKey and a RowKey.
  • if_match (str) — the client can specify the ETag for the entity on the request, to be compared against the ETag the service keeps, for optimistic concurrency. the update only goes through if the ETag you sent matches the value the server maintains, which signals the entity hasn't been modified since the client retrieved it. to force an unconditional update, set If-Match to the wildcard character (*). 💅

🦋 azure.cosmosdb.table.tableservice module

👑 class azure.cosmosdb.table.tableservice.TableService(account_name=None, account_key=None, sas_token=None, is_emulated=False, protocol='https', endpoint_suffix='core.windows.net', request_session=None, connection_string=None, socket_timeout=None)

Bases: azure.cosmosdb.table.common.storageclient.StorageClient

this is the main character class — the one managing your Azure Table resources 🌈

the Azure Table service offers structured storage in the form of tables. tables store data as collections of entities. entities are basically rows. an entity has a primary key and a set of properties. a property is a name + typed-value pair, kinda like a column. and here's the fun part: the Table service does not enforce any schema for tables, so two entities in the same table can totally have different sets of properties. if you want a schema, you can enforce it on the client side — your call, bestie. a table may contain any number of entities.

Variables

  • key_encryption_key (object) — the key-encryption-key you can optionally provide. if it's provided, it'll be used to encrypt/decrypt in the supported methods. for methods that require decryption, you gotta give either the key_encryption_key OR the resolver. if you provide both, the resolver wins. it must implement the following methods for APIs requiring encryption:
    • wrap_key(key) — wraps the specified key (bytes) using an algorithm of your choice. returns the encrypted key as bytes.
    • get_key_wrap_algorithm() — returns the algorithm used to wrap the specified symmetric key.
    • get_kid() — returns a string key id for this key-encryption-key.

and it must implement the following methods for APIs requiring decryption:

  • unwrap_key(key, algorithm) — returns the unwrapped form of the specified symmetric key using the string-specified algorithm.
  • get_kid() — returns a string key id for this key-encryption-key.
  • key_resolver_function(kid) (function) — a function to resolve keys, optionally provided by you. if provided, it'll be used to decrypt in supported methods. for methods requiring decryption, either the key_encryption_key OR the resolver must be provided. if both are provided, the resolver takes precedence. it uses the kid string to return a key-encryption-key implementing the interface defined above. iykyk 🧚
  • encryption_resolver_functions (function(partition_key, row_key, property_name)) — a function that takes in an entity's partition key, row key, and property name, and returns a boolean saying whether that property should be encrypted. vibe check per property, love that for us.
  • require_encryption (bool) — a flag you can set to make sure that all messages successfully uploaded to the queue, and all those downloaded and successfully read from the queue, are/were encrypted while on the server. if this flag is set, all required parameters for encryption/decryption must be provided. see the comments above on the key_encryption_key and resolver. 🔥

Parameters

  • account_name (str) — the storage account name. this is used to authenticate requests signed with an account key and to construct the storage endpoint. it's required unless a connection string is given. no account name, no party 💅
  • account_key (str) — the storage account key. this is used for shared key authentication.
  • sas_token (str) — a shared access signature token you use to authenticate requests instead of the account key. If you pass both account key and sas token, the account key will be used to sign. No cap. 💅
  • is_emulated (bool) — whether to use the emulator. Defaults to False. If you set this, it will override all other parameters besides connection_string and request_session. Iconic emulator energy.
  • protocol (str) — the protocol to use for requests. Defaults to https. Secure vibes only.
  • endpoint_suffix (str) — the host base component of the url, minus the account name. Defaults to Azure (core.windows.net). Override this to use the China cloud (core.chinacloudapi.cn). Cloud geography, bestie.
  • request_session (requests.Session) — the session object to use for http requests. Bring your own session.
  • connection_string (str) — if specified, this will override all other parameters besides request_session. See http://azure.microsoft.com/en-us/documentation/articles/storage-configure-connection-string/ for the connection string format. One string to rule them all.
  • socket_timeout (int) — if specified, this will override the default socket timeout. The timeout specified is in seconds. See DEFAULT_SOCKET_TIMEOUT in _constants.py for the default value. Timeout tea.

✨ batch(table_name, timeout=None) ✨

Creates a batch object which can be used as a context manager. Commits the batch on exit. Context manager realness!

Parameters

  • table_name (str) — the name of the table to commit the batch to. Name it, bestie.
  • timeout (int) — the server timeout, expressed in seconds. Clock is ticking.

✨ commit_batch(table_name, batch, timeout=None) ✨

Commits a TableBatch request. Send it.

Parameters

  • table_name (str) — the name of the table to commit the batch to.
  • batch (TableBatch) — the batch to commit.
  • timeout (int) — the server timeout, expressed in seconds.

Returns — A list of the batch responses corresponding to the requests in the batch. The items could either be an etag, in case of success, or an error object in case of failure. Success or oops, no in-between.

Return type — list(AzureBatchOperationError, str)

✨ create_table(table_name, fail_on_exist=False, timeout=None) ✨

Creates a new table in the storage account. New table, who dis?

Parameters

  • table_name (str) — the name of the table to create. The table name may contain only alphanumeric characters and cannot begin with a numeric character. It is case-insensitive and must be from 3 to 63 characters long. Rules are rules, bestie.
  • fail_on_exist (bool) — specifies whether to throw an exception if the table already exists. Drama if you want it.
  • timeout (int) — the server timeout, expressed in seconds.

Returns — A boolean indicating whether the table was created. If fail_on_exist was set to True, this will throw instead of returning false. No silent false for you.

Return type — bool

✨ delete_entity(table_name, partition_key, row_key, if_match='*', timeout=None) ✨

Deletes an existing entity in a table. Throws if the entity does not exist. Gone girl energy.

When an entity is successfully deleted, the entity is immediately marked for deletion and is no longer accessible to clients. The entity is later removed from the Table service during garbage collection. Garbage collection will handle the rest.

Parameters

  • table_name (str) — the name of the table containing the entity to delete.
  • partition_key (str) — the PartitionKey of the entity.
  • row_key (str) — the RowKey of the entity.
  • if_match (str) — the client may specify the ETag for the entity on the request in order to compare to the ETag maintained by the service for the purpose of optimistic concurrency. The delete operation will be performed only if the ETag sent by the client matches the value maintained by the server, indicating that the entity has not been modified since it was retrieved by the client. To force an unconditional delete, set If-Match to the wildcard character (*). Optimistic concurrency, but make it dramatic.
  • timeout (int) — the server timeout, expressed in seconds.

✨ delete_table(table_name, fail_not_exist=False, timeout=None) ✨

Deletes the specified table and any data it contains. Bye bye, data.

When a table is successfully deleted, it is immediately marked for deletion and is no longer accessible to clients. The table is later removed from the Table service during garbage collection. Same garbage collection saga.

Note that deleting a table is likely to take at least 40 seconds to complete. If an operation is attempted against the table while it was being deleted, an AzureConflictHttpError will be thrown. Don't poke the deleting table, bestie.

Parameters

  • table_name (str) — the name of the table to delete.
  • fail_not_exist (bool) — specifies whether to throw an exception if the table doesn't exist.
  • timeout (int) — the server timeout, expressed in seconds.

Returns — A boolean indicating whether the table was deleted. If fail_not_exist was set to True, this will throw instead of returning false. No quiet false for you.

Return type — bool

✨ exists(table_name, timeout=None) ✨

Returns a boolean indicating whether the table exists. Vibe check: does it exist?

Parameters

  • table_name (str) — the name of table to check for existence.
  • timeout (int) — the server timeout, expressed in seconds.

Returns — A boolean indicating whether the table exists. True or false, periodt.

Return type — bool

✨ generate_account_shared_access_signature(resource_types, permission, expiry, start=None, ip=None, protocol=None) ✨

Generates a shared access signature for the table service. Use the returned signature with the sas_token parameter of TableService. SAS token, slay.

Parameters

  • resource_types (ResourceTypes) — specifies the resource types that are accessible with the account SAS. What can they touch?
  • permission (AccountPermissions) — the permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Permission slip energy.
  • expiry (datetime or str) — the time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Expiration station.
  • start (datetime or str) — the time at which the shared access signature becomes valid. If omitted, start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. Start time tea.
  • ip (str) — specifies an IP address or a range of IP addresses from which to accept requests. If the IP address from which the request originates does not match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. IP gatekeeping, but make it secure.
  • protocol (str) — specifies the protocol permitted for a request made. The default value is https,http. See Protocol for possible values. Protocol options, iykyk.

Returns — A Shared Access Signature (sas) token. SAS token delivered.

Return type — str

✨ generate_table_shared_access_signature(table_name, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None, start_pk=None, start_rk=None, end_pk=None, end_rk=None) ✨

Generates a shared access signature for the table. Use the returned signature with the sas_token parameter of TableService. Table-level SAS, bestie.

Parameters

  • table_name (str) — the name of the table to create a SAS token for.
  • permission (TablePermissions) — the permissions that come with the shared access signature. Basically the user is only allowed to do the stuff these permissions say they can do. It's required unless you hand over an id that points at a stored access policy that already has this field inside it. And lowkey important: if it has already been specified in an associated stored access policy, you must omit this field. No double-dipping, bestie. 💅
  • expiry (datetime or str) — the moment the shared access signature stops working, i.e. becomes invalid. Required unless you give an id referencing a stored access policy that carries this field. Same rule as above: if it's already in the associated stored access policy, this field must be omitted. Also Azure always converts values to UTC — and if you pass in a date with no timezone info, it just assumes UTC. No cap. 🕐
  • start (datetime or str) — when the shared access signature becomes valid. If you skip it, the start time is assumed to be whenever the storage service actually receives the request. Azure still converts everything to UTC, and a date without timezone info gets assumed as UTC. ✨
  • id (str) — a unique value, up to 64 characters long, that correlates to a stored access policy. Wanna create a stored access policy? Use set_table_acl(). Iconic.
  • ip (str) — specifies an IP address or a range of IP addresses that requests will be accepted from. If the request's origin IP doesn't match the IP (or range) on the SAS token, the request is not authenticated. Like, for example, specifying sip='168.1.5.65' or sip='168.1.5.60-168.1.5.70' on the SAS restricts the request to just those IP addresses. 🚫
  • protocol (str) — specifies which protocol is permitted for a request. Default value is https,http. Check out Protocol for the possible values.
  • start_pk (str) — the minimum partition key accessible with this shared access signature. startpk must accompany startrk. Key values are inclusive. If you omit it, there's no lower bound on the table entities that can be accessed.
  • start_rk (str) — the minimum row key accessible with this shared access signature. startpk must accompany startrk. Key values are inclusive. If omitted, no lower bound on the table entities that can be accessed.
  • end_pk (str) — the maximum partition key accessible with this shared access signature. endpk must accompany endrk. Key values are inclusive. If omitted, there's no upper bound on the table entities that can be accessed.
  • end_rk (str) — the maximum row key accessible with this shared access signature. endpk must accompany endrk. Key values are inclusive. If omitted, no upper bound on the table entities that can be accessed.

Returns

A Shared Access Signature (sas) token. 🎀

Return type

str

get_entity

get_entity(table_name, partition_key, row_key, select=None,
           accept='application/json;odata=minimalmetadata',
           property_resolver=None, timeout=None)

Grabs an entity from the table you picked. Heads up though — it throws if the entity doesn't exist. Like, it's not gonna be nice about it. 😭

Parameters

  • table_name (str) — the name of the table you're pulling the entity from.
  • partition_key (str) — the PartitionKey of the entity.
  • row_key (str) — the RowKey of the entity.
  • select (str) — returns only the properties you actually want from the set. You're curating, bestie. ✨
  • accept (str) — specifies the accepted content type of the response payload. Peep TablePayloadFormat for the possible values.
  • property_resolver (func(pk, rk, prop_name, prop_value, service_edm_type)) — a function that, given the partition key, row key, property name, property value, and the property EdmType (if the service returned it), returns the EdmType of the property. Generally you use this if accept is set to JSON_NO_METADATA.
  • timeout (int) — the server timeout, expressed in seconds.

Returns

The retrieved entity. 🫶

Return type

Entity

get_table_acl

get_table_acl(table_name, timeout=None)

Returns the deets about any stored access policies set on the table that might get used with Shared Access Signatures.

Parameters

  • table_name (str) — the name of an existing table.
  • timeout (int) — the server timeout, expressed in seconds.

Returns

A dictionary of access policies associated with the table.

Return type

dict(str, AccessPolicy)

get_table_service_properties

get_table_service_properties(timeout=None)

Gets the properties of a storage account's Table service — that includes logging, analytics and CORS rules. 🌈

Parameters

  • timeout (int) — the server timeout, expressed in seconds.

Returns

The table service properties.

Return type

ServiceProperties

get_table_service_stats

get_table_service_stats(timeout=None)

Retrieves stats related to replication for the Table service. Quick heads up: it's only available when read-access geo-redundant replication is enabled for the storage account. If it's not enabled, don't even try. 💀

So with geo-redundant replication, Azure Storage keeps your data durable in two locations. In both of those locations, Azure Storage is constantly maintaining multiple healthy replicas of your data. The location where you read, create, update, or delete data is the primary storage account location. That primary location lives in the region you chose when you made the account via the Azure Management Azure classic portal — think North Central US, for example. The location your data gets replicated to is the secondary location. The secondary is automatically determined based on where the primary is; it sits in a second data center in the same region as the primary. Read-only access is available from the secondary location, if read-access geo-redundant replication is enabled for your storage account. Periodt. 👑

Parameters

  • timeout (int) — the timeout parameter, expressed in seconds.

Returns

The table service stats.

Return type

ServiceStats

insert_entity

insert_entity(table_name, entity, timeout=None)

Inserts a brand-new entity into the table. And it throws if an entity with the same PartitionKey and RowKey already exists. No duplicates allowed, sorry not sorry. 🙈

When you insert an entity into a table, you must specify values for the PartitionKey and RowKey system properties. Together those two form the primary key, and it has to be unique within the table. Both the PartitionKey and RowKey values must be string values, and each key value can be up to 64 KB in size. If you're using an integer value for the key, you should convert that integer to a fixed-width string, because they get canonically sorted. So like, you'd convert the value 1 to 0000001 to make sure the sorting behaves properly. 💅

Parameters

  • table_name (str) — the name of the table you're inserting the entity into.
  • entity (dict or Entity) — the entity to insert. Can be a dict or an entity object. It must contain a PartitionKey and a RowKey.
  • timeout (int) — the server timeout, expressed in seconds.

Returns

The etag of the inserted entity. ✨

Return type

str

insert_or_merge_entity

insert_or_merge_entity(table_name, entity, timeout=None)

Merges an existing entity, or inserts a new one if it doesn't already exist in the table. Best of both worlds, fr fr. 🌸

If insert_or_merge_entity is used to merge an entity, any properties from the previous entity get retained if the request doesn't define or include them. Nothing gets yeeted unless you say so.

Parameters

  • table_name (str) — the name of the table to insert or merge the entity into.
  • entity (dict or Entity) — the entity to insert or merge. Can be a dict or an entity object. It must contain a PartitionKey and a RowKey.
  • timeout (int) — the server timeout, expressed in seconds. ⏱️

Returns — the etag of the entity. 💖

Return type — str

💫 insert_or_replace_entity(table_name, entity, timeout=None)

Okay so this one is the iconic little chaos gremlin of the table world: it replaces an existing entity, or inserts a brand new one if that entity literally does not exist in the table yet. Because it can do either one, it's also known as an "upsert" operation. Slay. ✨

Heads up bestie: if you use insert_or_replace_entity to replace an entity, any properties from the previous entity will be removed if the new entity does not define them. It's giving fresh start, not merge. 🫶

Parameters

  • table_name (str) — the name of the table in which to insert or replace the entity.
  • entity (dict or Entity) — the entity to insert or replace. Could be a dict or an entity object. Must contain a PartitionKey and a RowKey.
  • timeout (int) — the server timeout, expressed in seconds.

Returns — the etag of the entity.

Return type — str

🌈 list_tables(num_results=None, marker=None, timeout=None)

Returns a generator to list the tables. The generator will lazily follow the continuation tokens the service hands back and stop when all tables have been returned, or when num_results is reached. Lazy in the good way, not the "I'll do it later" way. 💅

If num_results is specified and the account has more than that number of tables, the generator will have a populated next_marker field once it finishes. That marker can be used to create a new generator if more results are desired. No cap, that's how you keep the scroll going. 🔥

Parameters

  • num_results (int) — the maximum number of tables to return.
  • marker (obj) — an opaque continuation object. This value can be retrieved from the next_marker field of a previous generator object if num_results was specified and that generator has finished enumerating results. If specified, this generator will begin returning results from the point where the previous generator stopped. It's literally a bookmark but make it cloud. 🎀
  • timeout (int) — the server timeout, expressed in seconds. This function may make multiple calls to the service, in which case the timeout value specified will be applied to each individual call.

Returns — a generator which produces Table objects.

Return type — ListGenerator:

🦋 merge_entity(table_name, entity, if_match='*', timeout=None)

Updates an existing entity by merging the entity's properties. Throws if the entity does not exist. 😭

This operation does not replace the existing entity the way the update_entity operation does. A property cannot be removed with merge_entity. It's giving "add and glow up", not "delete and forget".

Any properties with null values are ignored. All other properties will be updated or added. 💖

Parameters

  • table_name (str) — the name of the table containing the entity to merge.
  • entity (dict or Entity) — the entity to merge. Could be a dict or an entity object. Must contain a PartitionKey and a RowKey.
  • if_match (str) — the client may specify the ETag for the entity on the request in order to compare to the ETag maintained by the service for the purpose of optimistic concurrency. The merge operation will be performed only if the ETag sent by the client matches the value maintained by the server, indicating that the entity has not been modified since it was retrieved by the client. To force an unconditional merge, set If-Match to the wildcard character (*). 🌟
  • timeout (int) — the server timeout, expressed in seconds.

Returns — the etag of the entity.

Return type — str

🧚 query_entities(table_name, filter=None, select=None, num_results=None, marker=None, accept='application/json;odata=minimalmetadata', property_resolver=None, timeout=None)

Returns a generator to list the entities in the table you specified. The generator will lazily follow the continuation tokens returned by the service and stop when all entities have been returned or num_results is reached. ✨

If num_results is specified and the account has more than that number of entities, the generator will have a populated next_marker field once it finishes. This marker can be used to create a new generator if more results are desired. Keep the party going bestie. 🎉

Parameters

  • table_name (str) — the name of the table to query.
  • filter (str) — returns only entities that satisfy the specified filter. Note that no more than 15 discrete comparisons are permitted within a $filter string. See http://msdn.microsoft.com/en-us/library/windowsazure/dd894031.aspx for more information on constructing filters. Fifteen. That's the limit. Don't push it. 💀
  • select (str) — returns only the desired properties of an entity from the set.
  • num_results (int) — the maximum number of entities to return.
  • marker (obj) — an opaque continuation object. This value can be retrieved from the next_marker field of a previous generator object if max_results was specified and that generator has finished enumerating results. If specified, this generator will begin returning results from the point where the previous generator stopped. 🫶
  • accept (str) — specifies the accepted content type of the response payload. See TablePayloadFormat for possible values.
  • property_resolver (func(pk, rk, prop_name, prop_value, service_edm_type)) — a function which, given the partition key, row key, property name, property value, and the property EdmType if returned by the service, returns the EdmType of the property. Generally used if accept is set to JSON_NO_METADATA. iykyk 💅
  • timeout (int) — the server timeout, expressed in seconds. This function may make multiple calls to the service, in which case the timeout value specified will be applied to each individual call.

Returns — a generator which produces Entity objects.

Return type — ListGenerator

💜 set_table_acl(table_name, signed_identifiers=None, timeout=None)

Sets stored access policies for the table that may be used with Shared Access Signatures. Very main character security energy. 👑

When you set permissions for a table, the existing permissions are replaced. To update the table's permissions, call get_table_acl() to fetch all access policies associated with the table, modify the access policy that you wish to change, and then call this function with the complete set of data to perform the update. Full send or nothing. 🎀

Okay so listen: when you establish a stored access policy on a table, it may take up to 30 seconds to take effect. During this interval, a shared access signature that is associated with the stored access policy will throw an AzureHttpError until the access policy becomes active. Not a bug, just the vibe settling in. 🙈

Parameters

  • table_name (str) — the name of an existing table.
  • signed_identifiers (dict(str, AccessPolicy)) — a dictionary of access policies to associate with the table. The dictionary may contain up to 5 elements. An empty dictionary will clear the access policies set on the service.
  • timeout (int) — the server timeout, expressed in seconds.

🌸 set_table_service_properties(logging=None, hour_metrics=None, minute_metrics=None, cors=None, timeout=None)

Sets the properties of a storage account's Table service, including Azure Storage Analytics. If an element (ex Logging) is left as None, the existing settings on the service for that functionality are preserved. For more information on Azure Storage Analytics, see https://msdn.microsoft.com/en-us/library/azure/hh343270.aspx. 📊

Parameters

  • logging (Logging) — the logging settings provide request logs.
  • hour_metrics (Metrics) — the hour metrics settings provide a summary of request statistics grouped by API in hourly aggregates for tables.
  • minute_metrics (Metrics) — the minute metrics settings provide request statistics for each minute for tables.
  • cors (list(CorsRule)) — bestie you can slide up to five CorsRule elements into this list. But if you hand over an empty list? every single CORS rule gets deleted and CORS is straight-up disabled for the service. 😭 For the full tea on CORS rules and how the evaluation logic actually works, see https://msdn.microsoft.com/en-us/library/azure/dn535601.aspx.
  • timeout (int) — the server timeout, expressed in seconds. ⏳

update_entity(table_name, entity, if_match='*', timeout=None)

Updates an existing entity in a table. Throws if the entity does not exist. And heads up — the update_entity operation replaces the entire entity, which is also how you remove properties. (yes, the whole thing, not just the bits you happened to mention 💅)

Parameters

  • table_name (str) — the name of the table holding the entity you're updating.
  • entity (dict or Entity) — the entity to update. Could be a dict or an entity object. It must contain a PartitionKey and a RowKey. no keys, no service, iykyk 🫶
  • if_match (str) — the client may specify the ETag for the entity on the request so it can be compared against the ETag the service maintains, for the purpose of optimistic concurrency. The update only happens if the ETag the client sent matches the value maintained by the server — which means the entity hasn't been modified since the client retrieved it. To force an unconditional update, set If-Match to the wildcard character (*). ⭐
  • timeout (int) — the server timeout, expressed in seconds. ⏳

Returns

The etag of the entity.

Return type

str

MODULE CONTENTS ✨

MODULE CONTENTS ✨

MODULE CONTENTS ✨

(three of them, because the original said it three times and we do not gatekeep 🌈)

💜 AZURE.COSMOSDB.TABLE.SHAREDACCESSSIGNATURE MODULE 💜

class TableSharedAccessSignature(account_name, account_key)

azure.cosmosdb.table.sharedaccesssignature.TableSharedAccessSignature(account_name, account_key)

Bases: azure.cosmosdb.table.common.sharedaccesssignature.SharedAccessSignature

Okay so this one is a factory for creating file and share access signature tokens with a common account name and account key. You've got options, bestie: either use the factory, or construct the appropriate service and call the generate_*_shared_access_signature method directly. both valid, pick your vibe 🦋

Parameters

  • account_name (str) — the storage account name used to generate the shared access signatures.
  • account_key (str) — the access key to generate the shares access signatures. 🔑

generate_table(table_name, permission=None, expiry=None, start=None, id=None, ip=None, protocol=None, start_pk=None, start_rk=None, end_pk=None, end_rk=None)

Generates a shared access signature for the table. Take the returned signature and use it with the sas_token parameter of TableService. 💫

Parameters

  • table_name (str) — name of table.
  • permission (TablePermissions) — the permissions associated with the shared access signature. The user is restricted to operations allowed by the permissions. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy.
  • expiry (datetime or str) — the time at which the shared access signature becomes invalid. Required unless an id is given referencing a stored access policy which contains this field. This field must be omitted if it has been specified in an associated stored access policy. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. 🕰️
  • start (datetime or str) — the time at which the shared access signature becomes valid. If omitted, the start time for this call is assumed to be the time when the storage service receives the request. Azure will always convert values to UTC. If a date is passed in without timezone info, it is assumed to be UTC. 🌅
  • id (str) — a unique value up to 64 characters in length that correlates to a stored access policy. To create a stored access policy, use set_table_service_properties.
  • ip (str) — specifies an IP address or a range of IP addresses from which to accept requests. If the IP address the request originates from doesn't match the IP address or address range specified on the SAS token, the request is not authenticated. For example, specifying sip=168.1.5.65 or sip=168.1.5.60-168.1.5.70 on the SAS restricts the request to those IP addresses. 🛡️
  • protocol (str) — specifies the protocol permitted for a request made. The default value is https,http. See Protocol for possible values.
  • start_pk (str) — the minimum partition key accessible with this shared access signature. startpk must accompany startrk. Key values are inclusive. If omitted, there is no lower bound on the table entities that can be accessed.
  • start_rk (str) — the minimum row key accessible with this shared access signature. startpk must accompany startrk. Key values are inclusive. If omitted, there is no lower bound on the table entities that can be accessed.
  • end_pk (str) — the maximum partition key accessible with this shared access signature. endpk must accompany endrk. Key values are inclusive. If omitted, there is no upper bound on the table entities that can be accessed.
  • end_rk (str) — the maximum row key accessible with this shared access signature. endpk must accompany endrk. Key values are inclusive. If omitted, there is no upper bound on the table entities that can be accessed.

AZURE

(yeah it's just… the word. iconic of it honestly 👑)

AUTHOR

unknown

2022, Microsoft

okay bestie that's the whole page, we did it 🎀 this was version 1.0.6, dated Apr 21, 2022, and you read every last crumb of it. go forth and slay your tables 💖✨

📦 where this page comes from