1.. default-domain:: py 2.. highlight:: python 3.. module:: fdb 4 5.. Required substitutions for api-common.rst.inc 6 7.. |database-type| replace:: ``Database`` 8.. |database-class| replace:: :class:`Database` 9.. |database-auto| replace:: the :func:`@fdb.transactional <transactional>` decorator 10.. |transaction-class| replace:: :class:`Transaction` 11.. |get-key-func| replace:: :func:`Transaction.get_key` 12.. |get-range-func| replace:: :func:`Transaction.get_range` 13.. |commit-func| replace:: :func:`Transaction.commit` 14.. |reset-func-name| replace:: :func:`reset <Transaction.reset>` 15.. |reset-func| replace:: :func:`Transaction.reset` 16.. |cancel-func| replace:: :func:`Transaction.cancel` 17.. |open-func| replace:: :func:`fdb.open` 18.. |on-error-func| replace:: :meth:`Transaction.on_error` 19.. |null-type| replace:: ``None`` 20.. |error-type| replace:: exception 21.. |error-raise-type| replace:: raise 22.. |future-cancel| replace:: :func:`Future.cancel` 23.. |max-watches-database-option| replace:: :func:`Database.options.set_max_watches` 24.. |retry-limit-database-option| replace:: :func:`Database.options.set_transaction_retry_limit` 25.. |timeout-database-option| replace:: :func:`Database.options.set_transaction_timeout` 26.. |max-retry-delay-database-option| replace:: :func:`Database.options.set_transaction_max_retry_delay` 27.. |snapshot-ryw-enable-database-option| replace:: :func:`Database.options.set_snapshot_ryw_enable` 28.. |snapshot-ryw-disable-database-option| replace:: :func:`Database.options.set_snapshot_ryw_disable` 29.. |future-type-string| replace:: a :ref:`future <api-python-future>` 30.. |read-your-writes-disable-option| replace:: :func:`Transaction.options.set_read_your_writes_disable` 31.. |retry-limit-transaction-option| replace:: :func:`Transaction.options.set_retry_limit` 32.. |timeout-transaction-option| replace:: :func:`Transaction.options.set_timeout` 33.. |max-retry-delay-transaction-option| replace:: :func:`Transaction.options.set_max_retry_delay` 34.. |snapshot-ryw-enable-transaction-option| replace:: :func:`Transaction.options.set_snapshot_ryw_enable` 35.. |snapshot-ryw-disable-transaction-option| replace:: :func:`Transaction.options.set_snapshot_ryw_disable` 36.. |lazy-iterator-object| replace:: generator 37.. |key-meth| replace:: :meth:`Subspace.key` 38.. |directory-subspace| replace:: :ref:`DirectorySubspace <api-python-directory-subspace>` 39.. |directory-layer| replace:: :class:`DirectoryLayer` 40.. |subspace| replace:: :class:`Subspace` 41.. |subspace-api| replace:: :ref:`subspaces <api-python-subspaces>` 42.. |as-foundationdb-key| replace:: :meth:`as_foundationdb_key` 43.. |as-foundationdb-value| replace:: :meth:`as_foundationdb_value` 44.. |tuple-layer| replace:: :ref:`tuple layer <api-python-tuple-layer>` 45.. |dir-path-type| replace:: a tuple 46.. |node-subspace| replace:: ``node_subspace`` 47.. |content-subspace| replace:: ``content_subspace`` 48.. |allow-manual-prefixes| replace:: ``allow_manual_prefixes`` 49 50.. include:: api-common.rst.inc 51 52####################### 53Python API 54####################### 55 56.. |block| replace:: :ref:`block <api-python-block>` 57.. |future-type| replace:: (:ref:`future <api-python-future>`) 58.. |future-object| replace:: :ref:`Future <api-python-future>` object 59.. |infrequent| replace:: *Infrequently used*. 60.. |slice-defaults| replace:: The default slice begin is ``''``; the default slice end is ``'\xFF'``. 61.. |byte-string| replace:: In Python 2, a byte string is a string of type ``str``. In Python 3, a byte string has type ``bytes``. 62 63Installation 64============ 65 66The FoundationDB Python API is compatible with Python 2.7 - 3.7. You will need to have a Python version within this range on your system before the FoundationDB Python API can be installed. Also please note that Python 3.7 no longer bundles a full copy of libffi, which is used for building the _ctypes module on non-macOS UNIX platforms. Hence, if you are using Python 3.7, you should make sure libffi is already installed on your system. 67 68On macOS, the FoundationDB Python API is installed as part of the FoundationDB installation (see :ref:`installing-client-binaries`). On Ubuntu or RHEL/CentOS, you will need to install the FoundationDB Python API manually. 69 70You can download the FoundationDB Python API source directly from :doc:`downloads`. 71 72.. note:: The Python language binding is compatible with FoundationDB client binaries of version 2.0 or higher. When used with version 2.0.x client binaries, the API version must be set to 200 or lower. 73 74After installation, the module ``fdb`` should be usable from your Python installation or path. (The system default python is always used by the client installer on macOS.) 75 76.. _api-python-versioning: 77 78API versioning 79============== 80 81When you import the ``fdb`` module, it exposes only one useful symbol: 82 83.. function:: api_version(version) 84 85 Specifies the version of the API that the application uses. This allows future versions of FoundationDB to make API changes without breaking existing programs. The current version of the API is |api-version|. 86 87.. note:: You must call ``fdb.api_version(...)`` before using any other part of the API. Once you have done so, the rest of the API will become available in the ``fdb`` module. This requirement includes use of the ``@fdb.transactional`` decorator, which is called when your module is imported. 88 89.. note:: |api-version-rationale| 90 91.. warning:: |api-version-multi-version-warning| 92 93For API changes between version 13 and |api-version| (for the purpose of porting older programs), see :doc:`release-notes`. 94 95Opening a database 96================== 97 98After importing the ``fdb`` module and selecting an API version, you probably want to open a :class:`Database` using :func:`open`:: 99 100 import fdb 101 fdb.api_version(610) 102 db = fdb.open() 103 104.. function:: open( cluster_file=None, event_model=None ) 105 106 |fdb-open-blurb| 107 108 .. param event_model:: Can be used to select alternate :ref:`api-python-event-models` 109 110.. data:: options 111 112 |network-options-blurb| 113 114 .. note:: |network-options-warning| 115 116 .. method :: fdb.options.set_trace_enable( output_directory=None ) 117 118 |option-trace-enable-blurb| 119 120 .. warning:: |option-trace-enable-warning| 121 122 .. method :: fdb.options.set_trace_max_logs_size(bytes) 123 124 |option-trace-max-logs-size-blurb| 125 126 .. method :: fdb.options.set_trace_roll_size(bytes) 127 128 |option-trace-roll-size-blurb| 129 130 .. method :: fdb.options.set_trace_format(format) 131 132 |option-trace-format-blurb| 133 134 .. method :: fdb.options.set_disable_multi_version_client_api() 135 136 |option-disable-multi-version-client-api| 137 138 .. method :: fdb.options.set_callbacks_on_external_threads() 139 140 |option-callbacks-on-external-threads| 141 142 .. method :: fdb.options.set_external_client_library(path_to_lib) 143 144 |option-external-client-library| 145 146 .. method :: fdb.options.set_external_client_directory(path_to_lib_directory) 147 148 |option-external-client-directory| 149 150 .. note:: |tls-options-burb| 151 152 .. method :: fdb.options.set_tls_plugin(plugin_path_or_name) 153 154 |option-tls-plugin-blurb| 155 156 .. method :: fdb.options.set_tls_cert_path(path_to_file) 157 158 |option-tls-cert-path-blurb| 159 160 .. method :: fdb.options.set_tls_key_path(path_to_file) 161 162 |option-tls-key-path-blurb| 163 164 .. method :: fdb.options.set_tls_verify_peers(criteria) 165 166 |option-tls-verify-peers-blurb| 167 168 .. method :: fdb.options.set_tls_cert_bytes(bytes) 169 170 |option-tls-cert-bytes| 171 172 .. method :: fdb.options.set_tls_key_bytes(bytes) 173 174 |option-tls-key-bytes| 175 176.. _api-python-keys: 177 178Keys and values 179=============== 180 181|keys-values-blurb| |byte-string| 182 183|keys-values-other-types-blurb| 184 185``as_foundationdb_key`` and ``as_foundationdb_value`` 186----------------------------------------------------- 187 188|as-foundationdb-blurb| 189 190.. warning :: |as-foundationdb-warning| 191 192KeyValue objects 193================ 194 195.. class :: KeyValue 196 197 Represents a single key-value pair in the database. This is a simple value type; mutating it won't affect your :class:`Transaction` or :class:`Database`. 198 199 KeyValue supports the Python iterator protocol so that you can unpack a key and value directly into two variables:: 200 201 for key, value in tr[begin:end]: 202 pass 203 204Attributes 205---------- 206 207.. attribute:: KeyValue.key 208.. attribute:: KeyValue.value 209 210Key selectors 211============= 212 213|keysel-blurb1| 214 215|keysel-blurb2| 216 217.. class :: KeySelector(key, or_equal, offset) 218 219 Creates a key selector with the given reference key, equality flag, and offset. It is usually more convenient to obtain a key selector with one of the following methods: 220 221.. classmethod:: KeySelector.last_less_than(key) 222 223 Returns a key selector referencing the last (greatest) key in the database less than the specified key. 224 225.. classmethod:: KeySelector.last_less_or_equal(key) 226 227 Returns a key selector referencing the last (greatest) key less than, or equal to, the specified key. 228 229.. classmethod:: KeySelector.first_greater_than(key) 230 231 Returns a key selector referencing the first (least) key greater than the specified key. 232 233.. classmethod:: KeySelector.first_greater_or_equal(key) 234 235 Returns a key selector referencing the first key greater than, or equal to, the specified key. 236 237``KeySelector + offset`` 238 Adding an integer ``offset`` to a ``KeySelector`` returns a key selector referencing a key ``offset`` keys after the original ``KeySelector``. FoundationDB does not efficiently resolve key selectors with large offsets, so :ref:`dont-use-key-selectors-for-paging`. 239 240``KeySelector - offset`` 241 Subtracting an integer ``offset`` from a ``KeySelector`` returns a key selector referencing a key ``offset`` keys before the original ``KeySelector``. FoundationDB does not efficiently resolve key selectors with large offsets, so :ref:`dont-use-key-selectors-for-paging`. 242 243Database objects 244================ 245 246.. class:: Database 247 248A |database-blurb1| |database-blurb2| 249 250.. note:: |database-sync| 251 252.. method:: Database.create_transaction() 253 254 Returns a new :class:`Transaction` object. Consider using the :func:`@fdb.transactional <transactional>` decorator to create transactions instead, since it will automatically provide you with appropriate retry behavior. 255 256.. |sync-read| replace:: This read is fully synchronous. 257.. |sync-write| replace:: This change will be committed immediately, and is fully synchronous. 258 259.. method:: Database.get(key) 260 261 Returns the value associated with the specified key in the database (or ``None`` if the key does not exist). |sync-read| 262 263``X = db[key]`` 264 Shorthand for ``X = db.get(key)``. 265 266.. method:: Database.get_key(key_selector) 267 268 Returns the key referenced by the specified :class:`KeySelector`. |sync-read| 269 270 |database-get-key-caching-blurb| 271 272.. method:: Database.get_range(begin, end[, limit, reverse, streaming_mode]) 273 274 Returns all keys ``k`` such that ``begin <= k < end`` and their associated values as a list of :class:`KeyValue` objects. Note the exclusion of ``end`` from the range. |sync-read| 275 276 Each of ``begin`` and ``end`` may be a key or a :class:`KeySelector`. Note that in the case of a :class:`KeySelector`, the exclusion of ``end`` from the range still applies. 277 278 If ``limit`` is specified, then only the first ``limit`` keys (and their values) in the range will be returned. 279 280 If ``reverse`` is True, then the last ``limit`` keys in the range will be returned in reverse order. 281 282 If ``streaming_mode`` is specified, it must be a value from the :data:`StreamingMode` enumeration. It provides a hint to FoundationDB about how to retrieve the specified range. This option should generally not be specified, allowing FoundationDB to retrieve the full range very efficiently. 283 284``X = db[begin:end]`` 285 Shorthand for ``X = db.get_range(begin, end)``. |slice-defaults| 286 287``X = db[begin:end:-1]`` 288 Shorthand for ``X = db.get_range(begin, end, reverse=True)``. |slice-defaults| 289 290.. method:: Database.get_range_startswith(prefix[, limit, reverse, streaming_mode]) 291 292 Returns all keys ``k`` such that ``k.startswith(prefix)``, and their associated values, as a list of :class:`KeyValue` objects. The ``limit``, ``reverse`` and ``streaming_mode`` parameters have the same meanings as in :meth:`Database.get_range()`. 293 294.. method:: Database.set(key, value) 295 296 Associates the given ``key`` and ``value``. Overwrites any prior value associated with ``key``. |sync-write| 297 298``db[key] = value`` 299 Shorthand for ``db.set(key, value)``. 300 301.. method:: Database.clear(key) 302 303 Removes the specified key (and any associated value), if it exists. |sync-write| 304 305``del db[key]`` 306 Shorthand for ``db.clear(key)``. 307 308.. method:: Database.clear_range(begin, end) 309 310 Removes all keys ``k`` such that ``begin <= k < end``, and their associated values. |sync-write| 311 312``del db[begin:end]`` 313 Shorthand for ``db.clear_range(begin, end)``. |slice-defaults| 314 315.. method:: Database.clear_range_startswith(prefix) 316 317 Removes all keys ``k`` such that ``k.startswith(prefix)``, and their associated values. |sync-write| 318 319.. method:: Database.get_and_watch(key) 320 321 Returns a tuple ``value, watch``, where ``value`` is the value associated with ``key`` or ``None`` if the key does not exist, and ``watch`` is a :class:`FutureVoid` that will become ready after ``value`` changes. 322 323 See :meth:`Transaction.watch` for a general description of watches and their limitations. 324 325.. method:: Database.set_and_watch(key, value) 326 327 Sets ``key`` to ``value`` and returns a :class:`FutureVoid` that will become ready after a subsequent change to ``value``. 328 329 See :meth:`Transaction.watch` for a general description of watches and their limitations. 330 331.. method:: Database.clear_and_watch(key) 332 333 Removes ``key`` (and any associated value) if it exists and returns a :class:`FutureVoid` that will become ready after the value is subsequently set. 334 335 See :meth:`Transaction.watch` for a general description of watches and their limitations. 336 337.. method:: Database.add(key, param) 338.. method:: Database.bit_and(key, param) 339.. method:: Database.bit_or(key, param) 340.. method:: Database.bit_xor(key, param) 341 342 These atomic operations behave exactly like the :ref:`associated operations <api-python-transaction-atomic-operations>` on :class:`Transaction` objects except that the change will immediately be committed, and is fully synchronous. 343 344 .. note :: |database-atomic-ops-idempotency-note| 345 346.. _api-python-database-options: 347 348Database options 349---------------- 350 351|database-options-blurb| 352 353.. method:: Database.options.set_location_cache_size(size) 354 355 |option-location-cache-size-blurb| 356 357.. method:: Database.options.set_max_watches(max_watches) 358 359 |option-max-watches-blurb| 360 361.. method:: Database.options.set_machine_id(id) 362 363 |option-machine-id-blurb| 364 365.. method:: Database.options.set_datacenter_id(id) 366 367 |option-datacenter-id-blurb| 368 369.. method:: Database.options.set_transaction_timeout(timeout) 370 371 |option-db-tr-timeout-blurb| 372 373.. method:: Database.options.set_transaction_retry_limit(retry_limit) 374 375 |option-db-tr-retry-limit-blurb| 376 377.. method:: Database.options.set_transaction_max_retry_delay(delay_limit) 378 379 |option-db-tr-max-retry-delay-blurb| 380 381.. method:: Database.options.set_snapshot_ryw_enable() 382 383 |option-db-snapshot-ryw-enable-blurb| 384 385.. method:: Database.options.set_snapshot_ryw_disable() 386 387 |option-db-snapshot-ryw-disable-blurb| 388 389.. _api-python-transactional-decorator: 390 391Transactional decoration 392======================== 393 394.. decorator:: transactional() 395 396 The ``@fdb.transactional`` decorator is a convenience designed to concisely wrap a function with logic to automatically create a transaction and retry until success. 397 398 For example:: 399 400 @fdb.transactional 401 def simple_function(tr, x, y): 402 tr[b'foo'] = x 403 tr[b'bar'] = y 404 405 The ``@fdb.transactional`` decorator makes ``simple_function`` a transactional function. All functions using this decorator must have an argument **named** ``tr``. This specially named argument is passed a transaction that the function can use to do reads and writes. 406 407 A caller of a transactionally decorated function can pass a :class:`Database` instead of a transaction for the ``tr`` parameter. Then a transaction will be created automatically, and automatically committed before returning to the caller. The decorator will retry calling the decorated function until the transaction successfully commits. 408 409 If ``db`` is a :class:`Database`, a call like :: 410 411 simple_function(db, 'a', 'b') 412 413 is equivalent to something like :: 414 415 tr = db.create_transaction() 416 while True: 417 try: 418 simple_function(tr, 'a', 'b') 419 tr.commit().wait() 420 break 421 except fdb.FDBError as e: 422 tr.on_error(e).wait() 423 424 A caller may alternatively pass an actual transaction to the ``tr`` parameter. In this case, the transactional function will not attempt to commit the transaction or to retry errors, since that is the responsibility of the caller who owns the transaction. This design allows transactionally decorated functions to be composed freely into larger transactions. 425 426 .. note :: |fdb-transactional-unknown-result-note| 427 428Transaction objects 429=================== 430 431.. class:: Transaction 432 433A ``Transaction`` object represents a FoundationDB database transaction. All operations on FoundationDB take place, explicitly or implicitly, through a ``Transaction``. 434 435|transaction-blurb1| 436 437|transaction-blurb2| 438 439|transaction-blurb3| 440 441The most convenient way to use Transactions is using the :func:`@fdb.transactional <transactional>` decorator. 442 443Keys and values in FoundationDB are byte strings (``str`` in Python 2.x, ``bytes`` in 3.x). To encode other data types, see the :mod:`fdb.tuple` module and :ref:`encoding-data-types`. 444 445Attributes 446---------- 447 448.. attribute:: Transaction.db 449 450 |db-attribute-blurb| 451 452Reading data 453------------ 454 455.. method:: Transaction.get(key) 456 457 Returns a |future-type| :class:`Value` associated with the specified key in the database. 458 459 To check whether the specified key was present in the database, call :meth:`Value.present()` on the return value. 460 461``X = tr[key]`` 462 Shorthand for ``X = tr.get(key)``. 463 464.. method:: Transaction.get_key(key_selector) 465 466 Returns the |future-type| :class:`Key` referenced by the specified :class:`KeySelector`. 467 468 |transaction-get-key-caching-blurb| 469 470.. method:: Transaction.get_range(begin, end[, limit, reverse, streaming_mode]) 471 472 Returns all keys ``k`` such that ``begin <= k < end`` and their associated values as an iterator yielding :class:`KeyValue` objects. Note the exclusion of ``end`` from the range. 473 474 Like a |future-object|, the returned iterator issues asynchronous read operations. It fetches the data in one or more efficient batches (depending on the value of the ``streaming_mode`` parameter). However, the iterator will block if iteration reaches a value whose read has not yet completed. 475 476 Each of ``begin`` and ``end`` may be a key or a :class:`KeySelector`. Note that in the case of a :class:`KeySelector`, the exclusion of ``end`` from the range still applies. 477 478 If ``limit`` is specified, then only the first ``limit`` keys (and their values) in the range will be returned. 479 480 If ``reverse`` is True, then the last ``limit`` keys in the range will be returned in reverse order. 481 482 If ``streaming_mode`` is specified, it must be a value from the :data:`StreamingMode` enumeration. It provides a hint to FoundationDB about how the returned container is likely to be used. The default is :data:`StreamingMode.iterator`. 483 484``X = tr[begin:end]`` 485 Shorthand for ``X = tr.get_range(begin, end)``. |slice-defaults| 486 487``X = tr[begin:end:-1]`` 488 Shorthand for ``X = tr.get_range(begin, end, reverse=True)``. |slice-defaults| 489 490.. method:: Transaction.get_range_startswith(prefix[, limit, reverse, streaming_mode]) 491 492 Returns all keys ``k`` such that ``k.startswith(prefix)``, and their associated values, as a container of :class:`KeyValue` objects (see :meth:`Transaction.get_range()` for a description of the returned container). 493 494 The ``limit``, ``reverse`` and ``streaming_mode`` parameters have the same meanings as in :meth:`Transaction.get_range()`. 495 496.. _api-python-snapshot-reads: 497 498Snapshot reads 499-------------- 500 501.. attribute:: Transaction.snapshot 502 503 |snapshot-blurb1| 504 505 |snapshot-blurb2| 506 507 |snapshot-blurb3| 508 509 |snapshot-blurb4| 510 511.. attribute:: Transaction.snapshot.db 512 513 |db-attribute-blurb| 514 515.. method:: Transaction.snapshot.get(key) 516 517 Like :meth:`Transaction.get`, but as a snapshot read. 518 519``X = tr.snapshot[key]`` 520 Shorthand for ``X = tr.snapshot.get(key)``. 521 522.. method:: Transaction.snapshot.get_key(key_selector) -> key 523 524 Like :meth:`Transaction.get_key`, but as a snapshot read. 525 526.. method:: Transaction.snapshot.get_range(begin, end[, limit, reverse, streaming_mode]) 527 528 Like :meth:`Transaction.get_range`, but as a snapshot read. 529 530``X = tr.snapshot[begin:end]`` 531 Shorthand for ``X = tr.snapshot.get_range(begin, end)``. |slice-defaults| 532 533``X = tr.snapshot[begin:end:-1]`` 534 Shorthand for ``X = tr.snapshot.get_range(begin, end, reverse=True)``. |slice-defaults| 535 536.. method:: Transaction.snapshot.get_range_startswith(prefix[, limit, reverse, streaming_mode]) 537 538 Like :meth:`Transaction.get_range_startswith`, but as a snapshot read. 539 540.. method:: Transaction.snapshot.get_read_version() 541 542 Identical to :meth:`Transaction.get_read_version` (since snapshot and serializable reads use the same read version). 543 544 545Writing data 546------------ 547 548.. |immediate-return| replace:: Returns immediately, having modified the snapshot represented by this :class:`Transaction`. 549 550.. method:: Transaction.set(key,value) 551 552 Associates the given ``key`` and ``value``. Overwrites any prior value associated with ``key``. |immediate-return| 553 554``tr[key] = value`` 555 Shorthand for ``tr.set(key,value)``. 556 557.. method:: Transaction.clear(key) 558 559 Removes the specified key (and any associated value), if it exists. |immediate-return| 560 561``del tr[key]`` 562 Shorthand for ``tr.clear(key)``. 563 564.. method:: Transaction.clear_range(begin, end) 565 566 Removes all keys ``k`` such that ``begin <= k < end``, and their associated values. |immediate-return| 567 568 .. note :: Unlike in the case of :meth:`get_range`, ``begin`` and ``end`` must be keys (byte strings), not :class:`KeySelector`\ s. (Resolving arbitrary key selectors would prevent this method from returning immediately, introducing concurrency issues.) 569 570``del tr[begin:end]`` 571 Shorthand for ``tr.clear_range(begin,end)``. |slice-defaults| 572 573.. method:: Transaction.clear_range_startswith(prefix) 574 575 Removes all the keys ``k`` such that ``k.startswith(prefix)``, and their associated values. |immediate-return| 576 577.. _api-python-transaction-atomic-operations: 578 579Atomic operations 580----------------- 581 582|atomic-ops-blurb1| 583 584|atomic-ops-blurb2| 585 586|atomic-ops-blurb3| 587 588.. warning :: |atomic-ops-warning| 589 590In each of the methods below, ``param`` should be a string appropriately packed to represent the desired value. For example:: 591 592 # wrong 593 tr.add('key', 1) 594 595 # right 596 import struct 597 tr.add('key', struct.pack('<q', 1)) 598 599.. method:: Transaction.add(key, param) 600 601 |atomic-add1| 602 603 |atomic-add2| 604 605.. method:: Transaction.bit_and(key, param) 606 607 |atomic-and| 608 609.. method:: Transaction.bit_or(key, param) 610 611 |atomic-or| 612 613.. method:: Transaction.bit_xor(key, param) 614 615 |atomic-xor| 616 617.. method:: Transaction.max(key, param) 618 619 |atomic-max1| 620 621 |atomic-max-min| 622 623.. method:: Transaction.byte_max(key, param) 624 625 |atomic-byte-max| 626 627.. method:: Transaction.min(key, param) 628 629 |atomic-min1| 630 631 |atomic-max-min| 632 633.. method:: Transaction.byte_min(key, param) 634 635 |atomic-byte-min| 636 637.. method:: Transaction.set_versionstamped_key(key, param) 638 639 |atomic-set-versionstamped-key-1| 640 641 |atomic-versionstamps-1| 642 643 |atomic-versionstamps-2| 644 645 |atomic-set-versionstamped-key-2| 646 647 .. warning :: |atomic-versionstamps-tuple-warning-key| 648 649.. method:: Transaction.set_versionstamped_value(key, param) 650 651 |atomic-set-versionstamped-value| 652 653 |atomic-versionstamps-1| 654 655 |atomic-versionstamps-2| 656 657 .. warning :: |atomic-versionstamps-tuple-warning-value| 658 659.. _api-python-committing: 660 661Committing 662---------- 663 664.. decorator:: transactional() 665 666 The ``transactional`` decorator makes it easy to write transactional functions which accept either a :class:`Database` or a :class:`Transaction` as a parameter and automatically commit. See :func:`@fdb.transactional <transactional>` for explanation and examples. 667 668.. method :: Transaction.commit() 669 670 Attempt to commit the changes made in the transaction to the database. Returns a :class:`FutureVoid` representing the asynchronous result of the commit. You **must** call the :meth:`Future.wait()` method on the returned :class:`FutureVoid`, which will raise an exception if the commit failed. 671 672 |commit-unknown-result-blurb| 673 674 |commit-outstanding-reads-blurb| 675 676 .. note :: Consider using the :func:`@fdb.transactional <transactional>` decorator, which not only calls :meth:`Database.create_transaction` and :meth:`Transaction.commit()` for you but also implements the required error handling and retry logic for transactions. 677 678 .. warning :: |used-during-commit-blurb| 679 680.. method :: Transaction.on_error(exception) 681 682 Determine whether an exception raised by a :class:`Transaction` method is retryable. Returns a :class:`FutureVoid`. You **must** call the :meth:`Future.wait()` method on the :class:`FutureVoid`, which will return after a delay if the exception was retryable, or re-raise the exception if it was not. 683 684 .. note :: Consider using the :func:`@fdb.transactional <transactional>` decorator, which calls this method for you. 685 686.. method :: Transaction.reset() 687 688 |transaction-reset-blurb| 689 690.. _api-python-cancel: 691 692.. method :: Transaction.cancel() 693 694 |transaction-cancel-blurb| 695 696 .. warning :: |transaction-reset-cancel-warning| 697 698 .. warning :: |transaction-commit-cancel-warning| 699 700.. _api-python-watches: 701 702Watches 703------- 704 705.. method:: Transaction.watch(key) 706 707 Creates a watch and returns a :class:`FutureVoid` that will become ready when the watch reports a change to the value of the specified key. 708 709 |transaction-watch-blurb| 710 711 |transaction-watch-committed-blurb| 712 713 |transaction-watch-error-blurb| 714 715 |transaction-watch-limit-blurb| 716 717.. _api-python-conflict-ranges: 718 719Conflict ranges 720--------------- 721 722.. note:: |conflict-range-note| 723 724|conflict-range-blurb| 725 726.. method:: Transaction.add_read_conflict_range(begin, end) 727 728 |add-read-conflict-range-blurb| 729 730.. method:: Transaction.add_read_conflict_key(key) 731 732 |add-read-conflict-key-blurb| 733 734.. method:: Transaction.add_write_conflict_range(begin, end) 735 736 |add-write-conflict-range-blurb| 737 738.. method:: Transaction.add_write_conflict_key(key) 739 740 |add-write-conflict-key-blurb| 741 742Versions 743-------- 744 745Most applications should use the read version that FoundationDB determines automatically during the transaction's first read, and ignore all of these methods. 746 747.. method :: Transaction.set_read_version(version) 748 749 |infrequent| Sets the database version that the transaction will read from the database. The database cannot guarantee causal consistency if this method is used (the transaction's reads will be causally consistent only if the provided read version has that property). 750 751.. method :: Transaction.get_read_version() 752 753 |infrequent| Returns a :class:`FutureVersion` representing the transaction's |future-type| read version. You must call the :meth:`Future.wait()` method on the returned object to retrieve the version as an integer. 754 755.. method :: Transaction.get_committed_version() 756 757 |infrequent| |transaction-get-committed-version-blurb| 758 759.. method :: Transaction.get_versionstamp() 760 761 |infrequent| |transaction-get-versionstamp-blurb| 762 763.. _api-python-transaction-options: 764 765Transaction options 766------------------- 767 768|transaction-options-blurb| 769 770.. _api-python-snapshot-ryw: 771 772.. method:: Transaction.options.set_snapshot_ryw_disable 773 774 |option-snapshot-ryw-disable-blurb| 775 776.. method:: Transaction.options.set_snapshot_ryw_enable 777 778 |option-snapshot-ryw-enable-blurb| 779 780.. method:: Transaction.options.set_priority_batch 781 782 |option-priority-batch-blurb| 783 784.. method:: Transaction.options.set_priority_system_immediate 785 786 |option-priority-system-immediate-blurb| 787 788 .. warning:: |option-priority-system-immediate-warning| 789 790.. method:: Transaction.options.set_causal_read_risky 791 792 |option-causal-read-risky-blurb| 793 794.. method:: Transaction.options.set_causal_write_risky 795 796 |option-causal-write-risky-blurb| 797 798.. _api-python-no-write-conflict-range: 799 800.. method:: Transaction.options.set_next_write_no_write_conflict_range 801 802 |option-next-write-no-write-conflict-range-blurb| 803 804 .. note:: |option-next-write-no-write-conflict-range-note| 805 806.. method:: Transaction.options.set_read_your_writes_disable 807 808 |option-read-your-writes-disable-blurb| 809 810 .. note:: |option-read-your-writes-disable-note| 811 812.. method:: Transaction.options.set_read_ahead_disable 813 814 |option-read-ahead-disable-blurb| 815 816.. method:: Transaction.options.set_access_system_keys 817 818 |option-access-system-keys-blurb| 819 820 .. warning:: |option-access-system-keys-warning| 821 822.. method:: Transaction.options.set_read_system_keys 823 824 |option-read-system-keys-blurb| 825 826 .. warning:: |option-read-system-keys-warning| 827 828.. method:: Transaction.options.set_retry_limit 829 830 |option-set-retry-limit-blurb1| 831 832 |option-set-retry-limit-blurb2| 833 834.. method:: Transaction.options.set_max_retry_delay 835 836 |option-set-max-retry-delay-blurb| 837 838.. _api-python-timeout: 839 840.. method:: Transaction.options.set_timeout 841 842 |option-set-timeout-blurb1| 843 844 |option-set-timeout-blurb2| 845 846 |option-set-timeout-blurb3| 847 848.. _api-python-future: 849 850Future objects 851============== 852 853|future-blurb1| 854 855.. _api-python-block: 856 857When a future object "blocks", what actually happens is determined by the :ref:`event model <api-python-event-models>`. A threaded program will block a thread, but a program using the gevent model will block a greenlet. 858 859All future objects are a subclass of the :class:`Future` type. 860 861.. class:: Future 862 863.. method:: Future.wait() 864 865 Blocks until the object is ready, and returns the object value (or raises an exception if the asynchronous function failed). 866 867.. method:: Future.is_ready() 868 869 Immediately returns true if the future object is ready, false otherwise. 870 871.. method:: Future.block_until_ready() 872 873 Blocks until the future object is ready. 874 875.. method:: Future.on_ready(callback) 876 877 Calls the specified callback function, passing itself as a single argument, when the future object is ready. If the future object is ready at the time :meth:`on_ready()` is called, the call may occur immediately in the current thread (although this behavior is not guaranteed). Otherwise, the call may be delayed and take place on the thread with which the client was initialized. Therefore, the callback is responsible for any needed thread synchronization (and/or for posting work to your application's event loop, thread pool, etc., as may be required by your application's architecture). 878 879.. warning:: |fdb-careful-with-callbacks-blurb| 880 881.. method:: Future.cancel() 882 883 |future-cancel-blurb| 884 885.. staticmethod:: Future.wait_for_any(*futures) 886 887 Does not return until at least one of the given future objects is ready. Returns the index in the parameter list of a ready future object. 888 889Asynchronous methods return one of the following subclasses of :class:`Future`: 890 891.. class:: Value 892 893 Represents a future string object and responds to the same methods as string in Python. They may be passed to FoundationDB methods that expect a string. 894 895.. method:: Value.present() 896 897 Returns ``False`` if the key used to request this value was not present in the database. For example:: 898 899 @fdb.transactional 900 def foo(tr): 901 val = tr[b'foo'] 902 if val.present(): 903 print 'Got value: %s' % val 904 else: 905 print 'foo was not present' 906 907.. class:: Key 908 909 Represents a future string object and responds to the same methods as string in Python. They may be passed to FoundationDB methods that expect a string. 910 911.. class:: FutureVersion 912 913 Represents a future version (integer). You must call the :meth:`Future.wait()` method on this object to retrieve the version as an integer. 914 915.. class:: FutureStringArray 916 917 Represents a future list of strings. You must call the :meth:`Future.wait()` method on this object to retrieve the list of strings. 918 919.. class:: FutureVoid 920 921 Represents a future returned from asynchronous methods that logically have no return value. 922 923 For a :class:`FutureVoid` object returned by :meth:`Transaction.commit()` or :meth:`Transaction.on_error()`, you must call the :meth:`Future.wait()` method, which will either raise an exception if an error occurred during the asynchronous call, or do nothing and return ``None``. 924 925.. _streaming-mode-python: 926 927Streaming modes 928=============== 929 930.. data:: StreamingMode 931 932|streaming-mode-blurb1| 933 934|streaming-mode-blurb2| 935 936The following streaming modes are available: 937 938.. data:: StreamingMode.iterator 939 940 *The default.* The client doesn't know how much of the range it is likely to used and wants different performance concerns to be balanced. 941 942 Only a small portion of data is transferred to the client initially (in order to minimize costs if the client doesn't read the entire range), and as the caller iterates over more items in the range larger batches will be transferred in order to maximize throughput. 943 944.. data:: StreamingMode.want_all 945 946 The client intends to consume the entire range and would like it all transferred as early as possible. 947 948.. data:: StreamingMode.small 949 950 |infrequent| Transfer data in batches small enough to not be much more expensive than reading individual rows, to minimize cost if iteration stops early. 951 952.. data:: StreamingMode.medium 953 954 |infrequent| Transfer data in batches sized in between small and large. 955 956.. data:: StreamingMode.large 957 958 |infrequent| Transfer data in batches large enough to be, in a high-concurrency environment, nearly as efficient as possible. If the client stops iteration early, some disk and network bandwidth may be wasted. The batch size may still be too small to allow a single client to get high throughput from the database, so if that is what you need consider :data:`StreamingMode.serial`. 959 960.. data:: StreamingMode.serial 961 962 Transfer data in batches large enough that an individual client can get reasonable read bandwidth from the database. If the client stops iteration early, considerable disk and network bandwidth may be wasted. 963 964.. data:: StreamingMode.exact 965 966 |infrequent| The client has passed a specific row limit and wants that many rows delivered in a single batch. This is not particularly useful in Python because iterator functionality makes batches of data transparent, so use :data:`StreamingMode.want_all` instead. 967 968 969.. _api-python-event-models: 970 971Event models 972============ 973 974By default, the FoundationDB Python API assumes that the calling program uses threads (as provided by the ``threading`` module) for concurrency. This means that blocking operations will block the current Python thread. This behavior can be changed by specifying the optional ``event_model`` parameter to the :func:`open` function. 975 976The following event models are available: 977 978``event_model=None`` 979 The default. Blocking operations will block the current Python thread. This is also fine for programs without any form of concurrency. 980 981``event_model="gevent"`` 982 The calling program uses the `gevent <http://www.gevent.org/>`_ module for single-threaded concurrency. Blocking operations will block the current greenlet. 983 984 The FoundationDB Python API has been tested with gevent versions 0.13.8 and 1.0rc2 and should work with all gevent 0.13 and 1.0 releases. 985 986 .. note:: The ``gevent`` event model on Windows requires gevent 1.0 or newer. 987 988``event_model="debug"`` 989 The calling program is threaded, but needs to be interruptible (by Ctrl-C). Blocking operations will poll, effectively blocking the current thread but responding to keyboard interrupts. This model is inefficient, but can be very useful for debugging. 990 991.. _api-python-release-notes: 992 993Errors 994====== 995 996Errors in the FoundationDB API are raised as exceptions of type :class:`FDBError`. These errors may be displayed for diagnostic purposes, but generally should be passed to :meth:`Transaction.on_error`. When using :func:`@fdb.transactional <transactional>`, appropriate errors will be retried automatically. 997 998.. class:: FDBError 999 1000.. attribute:: FDBError.code 1001 1002 An integer associated with the error type. 1003 1004.. attribute:: FDBError.description 1005 1006 A somewhat human-readable description of the error. 1007 1008.. warning:: You should use only :attr:`FDBError.code` for programmatic comparisons, as the description of the error may change at any time. Whenever possible, use the :meth:`Transaction.on_error()` method to handle :class:`FDBError` exceptions. 1009 1010.. _api-python-tuple-layer: 1011 1012Tuple layer 1013=========== 1014 1015.. module:: fdb.tuple 1016 1017|tuple-layer-blurb| 1018 1019.. note:: |tuple-layer-note| 1020 1021The tuple layer in the FoundationDB Python API supports tuples that contain elements of the following data types: 1022 1023+-----------------------+-------------------------------------------------------------------------------+ 1024| Type | Legal Values | 1025+=======================+===============================================================================+ 1026| ``None`` | Any ``value`` such that ``value == None`` | 1027+-----------------------+-------------------------------------------------------------------------------+ 1028| Byte string | Any ``value`` such that ``isinstance(value, bytes)`` | 1029+-----------------------+-------------------------------------------------------------------------------+ 1030| Unicode string | Any ``value`` such that ``isinstance(value, unicode)`` | 1031+-----------------------+-------------------------------------------------------------------------------+ 1032| Integer | Python 2.7: Any ``value`` such that ``isinstance(value, (int,long))`` and | 1033| | ``-2**2040+1 <= value <= 2**2040-1``. Python 3.x: Any ``value`` such that | 1034| | ``isinstance(value, int)`` and ``-2**2040+1 <= value <= 2**2040-1``. | 1035+-----------------------+-------------------------------------------------------------------------------+ 1036| Floating point number | Any ``value`` such that ``isinstance(value, fdb.tuple.SingleFloat)`` or | 1037| (single-precision) | ``isinstance(value, ctypes.c_float)`` | 1038+-----------------------+-------------------------------------------------------------------------------+ 1039| Floating point number | Any ``value`` such that ``isinstance(value, (ctypes.c_double, float))`` | 1040| (double-precision) | | 1041+-----------------------+-------------------------------------------------------------------------------+ 1042| Boolean | Any ``value`` such that ``isinstance(value, Boolean)`` | 1043+-----------------------+-------------------------------------------------------------------------------+ 1044| UUID | Any ``value`` such that ``isinstance(value, uuid.UUID)`` | 1045+-----------------------+-------------------------------------------------------------------------------+ 1046| Versionstamp | Any ``value`` such that ``isinstance(value, fdb.tuple.Versionstamp)`` | 1047+-----------------------+-------------------------------------------------------------------------------+ 1048| Tuple or List | Any ``value`` such that ``isinstance(value, (tuple, list))`` and each element | 1049| | within ``value`` is one of the supported types with a legal value. | 1050+-----------------------+-------------------------------------------------------------------------------+ 1051 1052If ``T`` is a Python tuple meeting these criteria, then:: 1053 1054 fdb.tuple.compare(T, fdb.tuple.unpack(fdb.tuple.pack(T))) == 0 1055 1056That is, any tuple meeting these criteria will have the same semantic value if serialized and deserialized. For 1057the most part, this also implies that ``T == fdb.tuple.unpack(fdb.tuple.pack(T))`` with the following caveats: 1058 1059- Any ``value`` of type ``ctypes.c_double`` is converted to the Python ``float`` type, but 1060 ``value.value == fdb.tuple.unpack(fdb.tuple.pack((value,)))[0]`` will be true (as long as ``value`` is not NaN). 1061- Any ``value`` of type ``ctypes.c_float`` is converted into a ``fdb.tuple.SingleFloat`` instance, but 1062 ``value.value == fdb.tuple.unpack(fdb.tuple.pack((value,)))[0].value`` will be true (as long as ``value.value`` is not NaN). 1063- Any ``value`` of type ``list`` or ``tuple`` is converted to a ``tuple`` type where the elements of the serialized and deserialized ``value`` 1064 will be equal (subject to these caveats) to the elements of the original ``value``. 1065 1066``import fdb.tuple`` 1067 Imports the FoundationDB tuple layer. 1068 1069.. method:: pack(tuple, prefix=b'') 1070 1071 Returns a key (byte string) encoding the specified tuple. If ``prefix`` is set, it will prefix the serialized 1072 bytes with the prefix string. This throws an error if any of the tuple's items are incomplete :class:`Versionstamp` 1073 instances. 1074 1075.. method:: pack_with_versionstamp(tuple, prefix=b'') 1076 1077 Returns a key (byte string) encoding the specified tuple. This method will throw an error unless 1078 exactly one of the items of the tuple is an incomplete :class:`Versionstamp` instance. (It will 1079 recurse down nested tuples if there are any to find one.) If so, it will produce a byte string 1080 that can be fed into :meth:`fdb.Transaction.set_versionstamped_key` and correctly fill in the 1081 versionstamp information at commit time so that when the key is re-read and deserialized, the 1082 only difference is that the :class:`Versionstamp` instance is complete and has the transaction version 1083 filled in. This throws an error if there are no incomplete :class:`Versionstamp` instances in the tuple 1084 or if there is more than one. 1085 1086.. method:: unpack(key) 1087 1088 Returns the tuple encoded by the given key. 1089 1090.. method:: has_incomplete_versionstamp(tuple) 1091 1092 Returns ``True`` if there is at least one element contained within the tuple that is a 1093 :class`Versionstamp` instance that is incomplete. If there are multiple incomplete 1094 :class:`Versionstamp` instances, this method will return ``True``, but trying to pack it into a 1095 byte string will result in an error. 1096 1097.. method:: range(tuple) 1098 1099 Returns a Python slice object representing all keys that encode tuples strictly starting with ``tuple`` (that is, all tuples of greater length than tuple of which tuple is a prefix). 1100 1101 Can be used to directly index a Transaction object to retrieve a range. For example:: 1102 1103 tr[ fdb.tuple.range(('A',2)) ] 1104 1105 returns all key-value pairs in the database whose keys would unpack to tuples like ('A', 2, x), ('A', 2, x, y), etc. 1106 1107.. method:: compare(tuple1, tuple2) 1108 1109 Compares two tuples in a way that respects the natural ordering of the elements within the tuples. It will 1110 return -1 if ``tuple1`` would sort before ``tuple2`` when performing an element-wise comparison of the two 1111 tuples, it will return 1 if ``tuple1`` would sort after ``tuple2``, and it will return 0 if the two 1112 tuples are equivalent. If the function must compare two elements of different types while doing the comparison, 1113 it will sort the elements based on their internal type codes, so comparisons are consistent if not necessarily 1114 semantically meaningful. Strings are sorted on their byte representation when encoded into UTF-8 (which may 1115 differ from the default sort when non-ASCII characters are included within the string), and UUIDs are sorted 1116 based on their big-endian byte representation. Single-precision floating point numbers are sorted before all 1117 double-precision floating point numbers, and for floating point numbers, -NaN is sorted before -Infinity which 1118 is sorted before finite numbers which are sorted before Infinity which is sorted before NaN. Different representations 1119 of NaN are not treated as equal. 1120 1121 Additionally, the tuple serialization contract is such that after they are serialized, the byte-string representations 1122 of ``tuple1`` and ``tuple2`` will sort in a manner that is consistent with this function. In particular, this function 1123 obeys the following contract:: 1124 1125 fdb.tuple.compare(tuple1, tuple2) == -1 if fdb.tuple.pack(tuple1) < fdb.tuple.pack(tuple2) else \ 1126 0 if fdb.tuple.pack(tuple2) == fdb.tuple.pack(tuple2) else 1 1127 1128 As byte order is the comparator used within the database, this comparator can be used to determine the order 1129 of keys within the database. 1130 1131.. class:: SingleFloat(value) 1132 1133 Wrapper around a single-precision floating point value. When constructed, the ``value`` parameter should either be 1134 an integral value, a ``float``, or a ``ctypes.c_float``. It will then properly store the value in its 1135 :attr:`SingleFloat.value` field (which should not be mutated). If the float does not fit within a IEEE 754 floating point 1136 integer, there may be a loss of precision. 1137 1138.. attribute:: SingleFloat.value 1139 1140 The underlying value of the ``SingleFloat`` object. This will have type ``float``. 1141 1142.. method:: SingleFloat.__eq__(other) 1143.. method:: SingleFloat.__ne__(other) 1144.. method:: SingleFloat.__lt__(other) 1145.. method:: SingleFloat.__le__(other) 1146.. method:: SingleFloat.__gt__(other) 1147.. method:: SingleFloat.__ge__(other) 1148 1149 Comparison functions for ``SingleFloat`` objects. This will sort according to the byte representation 1150 of the object rather than using standard float comparison. In particular, this means that ``-0.0 != 0.0`` 1151 and that the ``NaN`` values will sort in a way that is consistent with the :meth:`compare` method between 1152 tuples rather than using standard floating-point comparison. 1153 1154.. class:: Versionstamp(tr_version=None, user_version=0) 1155 1156 Used to represent values written by versionstamp operations within the tuple layer. This 1157 wraps a single byte array of length 12 that can be used to represent some global order 1158 of items within the database. These versions are composed of two separate components: 1159 (1) the 10-byte ``tr_version`` and (2) the two-byte ``user_version``. The ``tr_version`` 1160 is set by the database, and it is used to impose an order between different transactions. 1161 This order is guaranteed to be monotonically increasing over time for a given database. 1162 (In particular, it imposes an order that is consistent with a serialization order of 1163 the database's transactions.) If the client elects to leave the ``tr_version`` as its 1164 default value of ``None``, then the ``Versionstamp`` is considered "incomplete". This 1165 will cause the first 10 bytes of the serialized ``Versionstamp`` to be filled in with 1166 dummy bytes when serialized. When used with :meth:`fdb.Transaction.set_versionstamped_key`, 1167 an incomplete version can be used to ensure that a key gets written with the 1168 current transaction's version which can be useful for maintaining append-only data 1169 structures within the database. If the ``tr_version`` is set to something that is 1170 not ``None``, it should be set to a byte array of length 10. In this case, the 1171 ``Versionstamp`` is considered "complete". This is the usual case when one 1172 reads a serialized ``Versionstamp`` from the database. 1173 1174 The ``user_version`` should be specified as an integer, but it must fit within a two-byte 1175 unsigned integer. It is set by the client, and it is used to impose an order between items 1176 serialized within a single transaction. If left unset, then final two bytes of the serialized 1177 ``Versionstamp`` are filled in with a default (constant) value. 1178 1179 Sample usage of this class might be something like this:: 1180 1181 @fdb.transactional 1182 def write_versionstamp(tr, prefix): 1183 tr.set_versionstamped_key(fdb.tuple.pack_with_versionstamp((prefix, fdb.tuple.Versionstamp())), b'') 1184 return tr.get_versionstamp() 1185 1186 @fdb.transactional 1187 def read_versionstamp(tr, prefix): 1188 subspace = fdb.Subspace((prefix,)) 1189 for k, _ in tr.get_range(subspace.range().start, subspace.range().stop, 1): 1190 return subspace.unpack(k)[0] 1191 return None 1192 1193 db = fdb.open() 1194 del db[fdb.tuple.range(('prefix',))] 1195 tr_version = write_versionstamp(db, 'prefix').wait() 1196 v = read_versionstamp(db, 'prefix') 1197 assert v == fdb.tuple.Versionstamp(tr_version=tr_version) 1198 1199 Here, we serialize an incomplete ``Versionstamp`` and then write it using the ``set_versionstamped_key`` 1200 mutation so that it picks up the transaction's version information. Then when we read it 1201 back, we get a complete ``Versionstamp`` with the committed transaction's version. 1202 1203.. attribute:: Versionstamp.tr_version 1204 1205 The inter-transaction component of the ``Versionstamp`` class. It should be either ``None`` (to 1206 indicate an incomplete ``Versionstamp`` that will set the version later) or to some 10 byte value 1207 indicating the commit version and batch version of some transaction. 1208 1209.. attribute:: Versionstamp.user_version 1210 1211 The intra-transaction component of the ``Versionstamp`` class. It should be some number that can 1212 fit within two bytes (i.e., between 0 and 65,535 inclusive). It can be used to impose an order 1213 between items that are committed together in the same transaction. If left unset, then 1214 the versionstamp is assigned a (constant) default user version value. 1215 1216.. method:: Versionstamp.from_bytes(bytes) 1217 1218 Static initializer for ``Versionstamp`` instances that takes a serialized ``Versionstamp`` and 1219 creates an instance of the class. The ``bytes`` parameter should be a byte string of length 12. 1220 This method will serialize the version as a "complete" ``Versionstamp`` unless the dummy bytes 1221 are equal to the default transaction version assigned to incomplete ``Versionstamps``. 1222 1223.. method:: Versionstamp.is_complete() 1224 1225 Returns whether this version has been given a (non-``None``) ``tr_version`` or not. 1226 1227.. method:: Versionstamp.completed(tr_version) 1228 1229 If this ``Versionstamp`` is incomplete, this returns a copy of this instance except that the 1230 ``tr_version`` is filled in with the passed parameter. If the ``Versionstamp`` is already 1231 complete, it will raise an error. 1232 1233.. method:: Versionstamp.to_bytes() 1234 1235 Produces a serialized byte string corresponding to this versionstamp. It will have length 12 and 1236 will combine the ``tr_version`` and ``user_version`` to produce a byte string that 1237 lexicographically sorts appropriately with other ``Versionstamp`` instances. If this instance is 1238 incomplete, then the ``tr_version`` component gets filled in with dummy bytes that will cause it 1239 to sort after every complete ``Verionstamp``'s serialized bytes. 1240 1241.. method:: Versionstamp.__eq__(other) 1242.. method:: Versionstamp.__ne__(other) 1243.. method:: Versionstamp.__lt__(other) 1244.. method:: Versionstamp.__le__(other) 1245.. method:: Versionstamp.__gt__(other) 1246.. method:: Versionstamp.__ge__(other) 1247 1248 Comparison functions for ``Versionstamp`` objects. For two complete ``Versionstamps``, the 1249 ordering is first lexicographically by ``tr_version`` and then by ``user_version``. 1250 Incomplete ``Versionstamps`` are defined to sort after all complete ``Versionstamps`` (the idea 1251 being that for a given transaction, if a ``Versionstamp`` has been created as the result of 1252 some prior transaction's work, then the incomplete ``Versionstamp``, when assigned a version, 1253 will be assigned a greater version than the existing one), and for two incomplete ``Versionstamps``, 1254 the order is by ``user_version`` only. 1255 1256.. _api-python-subspaces: 1257 1258Subspaces 1259========= 1260 1261.. currentmodule:: fdb 1262 1263|subspace-blurb1| 1264 1265|subspace-blurb2| 1266 1267.. note:: For general guidance on subspace usage, see the discussion in the :ref:`Developer Guide <developer-guide-sub-keyspaces>`. 1268 1269.. class:: Subspace(prefixTuple=tuple(), rawPrefix="") 1270 1271 |subspace-blurb3| 1272 1273.. method:: Subspace.key() 1274 1275 |subspace-key-blurb| 1276 1277.. method:: Subspace.pack(tuple=tuple()) 1278 1279 |subspace-pack-blurb| 1280 1281.. method:: Subspace.pack_with_versionstamp(tuple) 1282 1283 Returns the key encoding the specified tuple in the subspace so that it may be used as the key in the 1284 :meth:`fdb.Transaction.set_versionstampe_key` method. The passed tuple must contain exactly one incomplete 1285 :class:`fdb.tuple.Versionstamp` instance or the method will raise an error. The behavior here is the same 1286 as if one used the :meth:`fdb.tuple.pack_with_versionstamp` method to appropriately pack together 1287 this subspace and the passed tuple. 1288 1289.. method:: Subspace.unpack(key) 1290 1291 |subspace-unpack-blurb| 1292 1293.. method:: Subspace.range(tuple=tuple()) 1294 1295 |subspace-range-blurb| 1296 1297 The range will be returned as a Python slice object, and may be used with any FoundationDB methods that require a range:: 1298 1299 r = subspace.range(('A', 2)) 1300 rng_itr1 = tr[r] 1301 rng_itr2 = tr.get_range(r.start, r.stop, limit=1) 1302 1303.. method:: Subspace.contains(key) 1304 1305 |subspace-contains-blurb| 1306 1307.. method:: Subspace.as_foundationdb_key() 1308 1309 |subspace-as-foundationdb-key-blurb| This method serves to support the :ref:`as_foundationdb_key() <api-python-keys>` convenience interface. 1310 1311.. method:: Subspace.subspace(tuple) 1312 1313 |subspace-subspace-blurb| 1314 1315 ``x = subspace[item]`` 1316 1317 Shorthand for ``x = subspace.subspace((item,))``. This function can be combined with the :meth:`Subspace.as_foundationdb_key()` convenience to turn this:: 1318 1319 s = fdb.Subspace(('x',)) 1320 tr[s.pack(('foo', 'bar', 1))] = '' 1321 1322 into this:: 1323 1324 s = fdb.Subspace(('x',)) 1325 tr[s['foo']['bar'][1]] = '' 1326 1327.. _api-python-directories: 1328 1329Directories 1330=========== 1331 1332|directory-blurb1| 1333 1334.. note:: For general guidance on directory usage, see the discussion in the :ref:`Developer Guide <developer-guide-directories>`. 1335 1336|directory-blurb2| 1337 1338|directory-blurb3| 1339 1340.. data:: directory 1341 1342 The default instance of :class:`DirectoryLayer`. 1343 1344.. class:: DirectoryLayer(node_subspace=Subspace(rawPrefix="\xfe"), content_subspace=Subspace(), allow_manual_prefixes=False) 1345 1346 |directory-layer-blurb| 1347 1348.. method:: DirectoryLayer.create_or_open(tr, path, layer=None) 1349 1350 |directory-create-or-open-blurb| 1351 1352 If the byte string ``layer`` is specified and the directory is new, it is recorded as the layer; if ``layer`` is specified and the directory already exists, it is compared against the layer specified when the directory was created, and the method will |error-raise-type| an |error-type| if they differ. 1353 1354 |directory-create-or-open-return-blurb| 1355 1356.. method:: DirectoryLayer.open(tr, path, layer=None) 1357 1358 |directory-open-blurb| 1359 1360 If the byte string ``layer`` is specified, it is compared against the layer specified when the directory was created, and the method will |error-raise-type| an |error-type| if they differ. 1361 1362 |directory-create-or-open-return-blurb| 1363 1364.. method:: DirectoryLayer.create(tr, path, layer=None, prefix=None) 1365 1366 |directory-create-blurb| 1367 1368 If the byte string ``prefix`` is specified, the directory is created with the given physical prefix; otherwise a prefix is allocated automatically. 1369 1370 If the byte string ``layer`` is specified, it is recorded with the directory and will be checked by future calls to open. 1371 1372 |directory-create-or-open-return-blurb| 1373 1374.. method:: DirectoryLayer.move(tr, old_path, new_path) 1375 1376 |directory-move-blurb| 1377 1378 |directory-move-return-blurb| 1379 1380.. method:: DirectoryLayer.remove(tr, path) 1381 1382 |directory-remove-blurb| 1383 1384 .. warning:: |directory-remove-warning| 1385 1386.. method:: DirectoryLayer.remove_if_exists(tr, path) 1387 1388 |directory-remove-if-exists-blurb| 1389 1390 .. warning:: |directory-remove-warning| 1391 1392.. method:: DirectoryLayer.list(tr, path=()) 1393 1394 Returns a list of names of the immediate subdirectories of the directory at ``path``. Each name is a unicode string representing the last component of a subdirectory's path. 1395 1396.. method:: DirectoryLayer.exists(tr, path) 1397 1398 |directory-exists-blurb| 1399 1400.. method:: DirectoryLayer.get_layer() 1401 1402 |directory-get-layer-blurb| 1403 1404.. method:: DirectoryLayer.get_path() 1405 1406 |directory-get-path-blurb| 1407 1408.. _api-python-directory-subspace: 1409 1410DirectorySubspace 1411----------------- 1412 1413|directory-subspace-blurb| 1414 1415.. method:: DirectorySubspace.move_to(tr, new_path) 1416 1417 |directory-move-to-blurb| 1418 1419 |directory-move-return-blurb| 1420 1421.. _api-python-locality: 1422 1423Locality information 1424==================== 1425 1426.. module:: fdb.locality 1427 1428|locality-api-blurb| 1429 1430.. method:: fdb.locality.get_boundary_keys(db_or_tr, begin, end) 1431 1432 |locality-get-boundary-keys-blurb| 1433 1434 |locality-get-boundary-keys-db-or-tr| 1435 1436 Like a |future-object|, the returned container issues asynchronous read operations to fetch the data in the range and may block while iterating over its values if the read has not completed. 1437 1438 |locality-get-boundary-keys-warning-danger| 1439 1440.. method:: fdb.locality.get_addresses_for_key(tr, key) 1441 1442 Returns a :class:`fdb.FutureStringArray`. You must call the :meth:`fdb.Future.wait()` method on this object to retrieve a list of public network addresses as strings, one for each of the storage servers responsible for storing ``key`` and its associated value. 1443