Merge pull request #5 from TreeBen77/orderedapi

Added support for Ordered Data Stores

docs/source/datastore.rst

@@ -57,7 +57,6 @@ Data Store
         :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
         :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
         :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
-
 
     .. method:: get(key)
 
@@ -189,6 +188,132 @@ Data Store
         :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
         :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
 
+.. class:: OrderedDataStore
+
+    Class for interacting with the Ordered DataStore API for a specific Ordered DataStore.
+
+    .. versionadded:: 1.2
+
+    .. warning::
+
+        This class is not designed to be created by users. It is returned by :meth:`Experince.get_ordered_data_store`.
+
+    .. attribute:: name 
+
+        :type: str
+
+    .. attribute:: scope 
+
+        :type: Optional[str]
+
+    .. attribute:: experince 
+
+        :type: :meth:`rblx-open-cloud.Experince`
+
+    .. method:: sort_keys(descending=True, limit=None, min=None, max=None)
+
+        Returns a list of keys and their values.
+
+        The example below would list all keys, along with their value.
+
+        .. code:: py
+
+            for key in datastore.sort_keys():
+                print(key.name, key.value)
+        
+        You can simply convert it to a list by putting it in the list function:
+
+        .. code:: py
+
+            list(datastore.sort_keys())
+
+        Lua equivalent: `OrderedDataStore:GetSortedAsync() <https://create.roblox.com/docs/reference/engine/classes/OrderedDataStore#GetSortedAsync>`__
+
+        :param bool descending: Wether the largest number should be first, or the smallest.
+        :param bool limit: Max number of entries to loop through.
+        :param int min: Minimum entry value to retrieve
+        :param int max: Maximum entry value to retrieve.
+
+        :returns: Iterable[:class:`SortedEntry`]
+        :raises ValueError: The :class:`OrderedDataStore` doesn't have a scope.
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to list data store keys.
+        :raises rblx-open-cloud.NotFound: The datastore or key does not exist
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+    .. note::
+
+        Unlike :meth:`DataStore.list_keys`, this function is unable to work without a scope, this is an Open Cloud limitation. You can still use other functions with the normal ``scope/key`` syntax when scope is ``None``.
+
+    .. method:: get(key)
+
+        Gets the value of a key.
+
+        Lua equivalent: `OrderedDataStore:GetAsync() <https://create.roblox.com/docs/reference/engine/classes/OrderedDataStore#GetAsync>`__
+
+        :param str key: The key to find.
+
+        :returns: int
+        :raises ValueError: The :class:`OrderedDataStore` doesn't have a scope and the key must be formatted as ``scope/key``
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to read data store keys.
+        :raises rblx-open-cloud.NotFound: The datastore or key does not exist
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+    .. method:: set(key, value, exclusive_create=False, exclusive_update=False)
+
+        Sets the value of a key.
+
+        Lua equivalent: `OrderedDataStore:SetAsync() <https://create.roblox.com/docs/reference/engine/classes/OrderedDataStore#SetAsync>`__
+
+        :param str key: The key to create/update.
+        :param int value: The new integer value. Must be positive.
+        :param bool exclusive_create: Wether to fail if the key already has a value.
+        :param bool exclusive_update: Wether to fail if the key does not have a value.
+
+        :returns: int
+        :raises ValueError: The :class:`OrderedDataStore` doesn't have a scope and the key must be formatted as ``scope/key`` or both ``exclusive_create`` and ``exclusive_update`` are ``True``.
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to write data store keys.
+        :raises rblx-open-cloud.NotFound: The datastore or key does not exist
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+        :raises rblx-open-cloud.PreconditionFailed: ``exclusive_create`` is ``True`` and the key already has a value, or ``exclusive_update`` is ``True`` and there is no pre-existing value.
+
+    .. method:: increment(key, increment)
+
+        Increments the value of a key.
+
+        Lua equivalent: `OrderedDataStore:IncrementAsync() <https://create.roblox.com/docs/reference/engine/classes/OrderedDataStore#IncrementAsync>`__
+
+        :param str key: The key to increment.
+        :param int increment: The amount to increment the key by. You can use negative numbers to decrease the value.
+
+        :returns: int
+        :raises ValueError: The :class:`OrderedDataStore` doesn't have a scope and the key must be formatted as ``scope/key``
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to write data store keys.
+        :raises rblx-open-cloud.NotFound: The datastore or key does not exist
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+    .. method:: remove(key)
+
+        Removes a key.
+
+        Lua equivalent: `OrderedDataStore:RemoveAsync() <https://create.roblox.com/docs/reference/engine/classes/OrderedDataStore#RemoveAsync>`__
+
+        :param str key: The key to remove.
+
+        :raises ValueError: The :class:`OrderedDataStore` doesn't have a scope and the key must be formatted as ``scope/key``
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to write data store keys.
+        :raises rblx-open-cloud.NotFound: The datastore or key does not exist
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
 .. class:: EntryInfo
 
     Contains data about an entry such as version ID, timestamps, users and metadata.
@@ -272,7 +397,7 @@ Data Store
 
 .. class:: ListedEntry
 
-    Object which contains a entry's key and scope.
+    Object which contains an entry's key and scope.
 
     .. warning::
 
@@ -288,4 +413,32 @@ Data Store
 
         The Entry's scope
 
-        :type: str
+        :type: str
+
+.. class:: SortedEntry
+
+    Object which contains a sorted entry's key, scope, and value.
+
+    .. versionadded:: 1.2
+
+    .. warning::
+
+        This class is not designed to be created by users. It is returned by :meth:`OrderedDataStore.sort_keys`.
+
+    .. attribute:: key 
+
+        The Entry's key
+
+        :type: str
+
+    .. attribute:: scope
+
+        The Entry's scope
+
+        :type: str
+
+    .. attribute:: value
+
+        The Entry's value
+
+        :type: int

docs/source/experience.rst

@@ -27,9 +27,6 @@ Experience
          :param str name: The name of the data store
          :param Union[str, None] scope: A string specifying the scope, can also be None.
          :returns: :class:`rblx-open-cloud.DataStore`
-
-         .. note::
-            Ordered DataStores are still in alpha, to use them you must `sign up for the beta <https://devforum.roblox.com/t/opencloud-ordered-datastores/2062532>`__ and then `install the beta library <https://github.com/TreeBen77/rblx-open-cloud/tree/orderedapi>__`
 
    .. method:: list_data_stores(prefix="", scope="global")
 
@@ -60,6 +57,18 @@ Experience
          :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
          :raises rblx-open-cloud.ServiceUnavailable: Roblox's services as currently experiencing downtime.
          :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+   .. method:: get_ordered_data_store(name, scope="global")
+
+         Creates a :class:`rblx-open-cloud.OrderedDataStore` with the provided name and scope.
+
+         If ``scope`` is ``None`` then keys require to be formatted like ``scope/key`` and :meth:`OrderedDataStore.sort_keys` will not work.
+
+         Lua equivalent: `DataStoreService:GetDataStore() <https://create.roblox.com/docs/reference/engine/classes/DataStoreService#GetOrderedDataStore>`__
+
+         :param str name: The name of the data store
+         :param Union[str, None] scope: A string specifying the scope, can also be None.
+         :returns: :class:`rblx-open-cloud.DataStore`
 
    .. method:: publish_message(topic, data)
 

rblxopencloud/__init__.py

@@ -7,7 +7,7 @@
 
 from typing import Literal
 
-VERSION: str = "1.1.0"
-VERSION_INFO: Literal['alpha', 'beta', 'final'] = "final"
+VERSION: str = "1.2.0"
+VERSION_INFO: Literal['alpha', 'beta', 'final'] = "beta"
 
-del Literal
+del Literal