slipstream.caching
==================

.. py:module:: slipstream.caching

.. autoapi-nested-parse::

   Slipstream caching.



Attributes
----------

.. autoapisummary::

   slipstream.caching.MB
   slipstream.caching.MINUTES


Classes
-------

.. autoapisummary::

   slipstream.caching.Cache


Module Contents
---------------

.. py:data:: MB
   :value: 1048576


.. py:data:: MINUTES
   :value: 60


.. py:class:: Cache(path: str, options: Optional[rocksdict.Options] = None, column_families: Dict[str, rocksdict.Options] | None = None, access_type: rocksdict.AccessType = AccessType.read_write(), target_table_size: int = 25 * MB, number_of_locks: int = 16)

   Bases: :py:obj:`slipstream.interfaces.ICache`


   Create a RocksDB database in the specified folder.

   >>> cache = Cache('db/mycache')            # doctest: +SKIP

   The cache instance acts as a callable to store data:

   >>> cache('key', {'msg': 'Hello World!'})  # doctest: +SKIP
   >>> cache['key']                           # doctest: +SKIP
   {'msg': 'Hello World!'}


   .. py:attribute:: name


   .. py:attribute:: db


   .. py:method:: transaction(key: slipstream.interfaces.Key)
      :async:


      Lock the db entry while using the context manager.

      >>> async with cache.transaction('fish'):    # doctest: +SKIP
      ...     cache['fish'] = '🐟'

      - This works for asynchronous code (not multi-threading/processing)
      - While locked, other transactions on the same key will block
      - Actions outside of transaction blocks ignore ongoing transactions
      - Reads aren't limited by ongoing transactions



   .. py:method:: set_dumps(dumps: Callable[[Any], bytes]) -> None

      Set custom dumps function.



   .. py:method:: set_loads(dumps: Callable[[bytes], Any]) -> None

      Set custom loads function.



   .. py:method:: set_read_options(read_opt: rocksdict.ReadOptions) -> None

      Set custom read options.



   .. py:method:: set_write_options(write_opt: rocksdict.WriteOptions) -> None

      Set custom write options.



   .. py:method:: get(key: slipstream.interfaces.Key | list[slipstream.interfaces.Key], default: T = None, read_opt: rocksdict.ReadOptions | None = None) -> Any | T

      Get item from database by key.



   .. py:method:: put(key: slipstream.interfaces.Key, value: Any, write_opt: rocksdict.WriteOptions | None = None) -> None

      Put item in database using key.



   .. py:method:: delete(key: slipstream.interfaces.Key, write_opt: rocksdict.WriteOptions | None = None) -> None

      Delete item from database.



   .. py:method:: key_may_exist(key: slipstream.interfaces.Key, fetch: bool = False, read_opt: Optional[rocksdict.ReadOptions] = None) -> bool | Tuple[bool, Any]

      Check if a key exist without performing IO operations.



   .. py:method:: iter(read_opt: rocksdict.ReadOptions | None = None) -> rocksdict.RdictIter

      Get iterable.



   .. py:method:: items(backwards: bool = False, from_key: str | int | float | bytes | bool | None = None, read_opt: rocksdict.ReadOptions | None = None) -> rocksdict.rocksdict.RdictItems

      Get tuples of key-value pairs.



   .. py:method:: keys(backwards: bool = False, from_key: str | int | float | bytes | bool | None = None, read_opt: rocksdict.ReadOptions | None = None) -> rocksdict.rocksdict.RdictKeys

      Get keys.



   .. py:method:: values(backwards: bool = False, from_key: Optional[slipstream.interfaces.Key] = None, read_opt: Optional[rocksdict.ReadOptions] = None) -> rocksdict.rocksdict.RdictValues

      Get values.



   .. py:method:: ingest_external_file(paths: List[str], opts: rocksdict.IngestExternalFileOptions = IngestExternalFileOptions()) -> None

      Load list of SST files into current column family.



   .. py:method:: get_column_family(name: str) -> rocksdict.Rdict

      Get column family by name.



   .. py:method:: get_column_family_handle(name: str) -> rocksdict.ColumnFamily

      Get column family handle by name.



   .. py:method:: drop_column_family(name: str) -> None

      Drop column family by name.



   .. py:method:: create_column_family(name: str, options: rocksdict.Options = Options()) -> rocksdict.Rdict

      Craete column family.



   .. py:method:: delete_range(begin: slipstream.interfaces.Key, end: slipstream.interfaces.Key, write_opt: rocksdict.WriteOptions | None = None) -> None

      Delete database items, excluding end.



   .. py:method:: snapshot() -> rocksdict.Snapshot

      Create snapshot of current column family.



   .. py:method:: path() -> str

      Get current database path.



   .. py:method:: set_options(options: Dict[str, str]) -> None

      Set options for current column family.



   .. py:method:: property_value(name: str) -> str | None

      Get property by name from current column family.



   .. py:method:: property_int_value(name: str) -> int | None

      Get property as int by name from current column family.



   .. py:method:: latest_sequence_number() -> int

      Get sequence number of the most recent transaction.



   .. py:method:: live_files() -> List[Dict[str, Any]]

      Get list of all table files with their level, start/end key.



   .. py:method:: compact_range(begin: Optional[slipstream.interfaces.Key], end: Optional[slipstream.interfaces.Key], compact_opt: rocksdict.CompactOptions = CompactOptions()) -> None

      Run manual compaction on range for the current column family.



   .. py:method:: close() -> None

      Flush memory to disk, and drop the current column family.



   .. py:method:: flush(wait: bool = True) -> None

      Manually flush the current column family.



   .. py:method:: flush_wal(sync: bool = True) -> None

      Manually flush the WAL buffer.



   .. py:method:: destroy(options: rocksdict.Options = Options()) -> None

      Delete the database.