Merge branch 'main' of https://github.com/TreeBen77/rblx-open-cloud i…

…nto orderedapi

.github/workflows/python-publish.yml

@@ -30,6 +30,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install build
+        pip install requests
     - name: Build package
       run: python -m build
     - name: Publish package

README.md

@@ -4,6 +4,8 @@ Python API wrapper for [Roblox Open Cloud](https://create.roblox.com/docs/open-c
 
 **Documentation: https://rblx-open-cloud.readthedocs.io**
 
+**Discord Server: https://discord.gg/gEBdHNAR46**
+
 ## Quickstart
 
 ### Getting Started
@@ -13,23 +15,21 @@ Python API wrapper for [Roblox Open Cloud](https://create.roblox.com/docs/open-c
     pip install rblx-open-cloud
     ```
 
-2. Create an API key from the [Creator Dashboard](https://create.roblox.com/credentials). You can read [Managing API Keys](https://create.roblox.com/docs/open-cloud/managing-api-keys) if you get stuck.
-
-3. Add the following code to your project and replace `api-key-from-step-2` with the key you generated.
-    ```py
-    # create a Universe object with your universe/experience ID and your api key
-    # TODO: replace '13058' with your universe ID
-    universe = rblxopencloud.Universe(13058, api_key="api-key-from-step-2")
-    ```
-    If you don't know how to get the universe or place ID read [Publishing Places with API Keys](https://create.roblox.com/docs/open-cloud/publishing-places-with-api-keys#:~:text=Find%20the%20experience,is%206985028626.)
+2. Create an API key from the [Creator Dashboard](https://create.roblox.com/credentials). You can read [Managing API Keys](https://create.roblox.com/docs/open-cloud/managing-api-keys) for help.
 
-4. If you want to start by accessing your game's data stores go to [Data Stores](#accessing-data-stores) otherwise, you can go to [Messaging Service](#publishing-to-message-service) if you want to publish messages to live game servers, or [Place Publishing](#publish-or-save-a-rbxl-file) if you'd like to upload `.rbxl` files to Roblox.**
+You've got the basics down, below are examples for some of the APIs.
 
 ### Accessing Data Stores
-**NOTE: Roblox doesn't support access to ordered data stores via open cloud at the moment.**
+**NOTE: Roblox doesn't support access to ordered data stores via open cloud yet.**
 ```py
+import rblxopencloud
+
+# create an Experience object with your experience ID and your api key
+# TODO: replace '13058' with your experience ID
+experience = rblxopencloud.Experience(13058, api_key="api-key-from-step-2")
+
 # get the data store, using the data store name and scope (defaults to global)
-datastore = universe.get_data_store("data-store-name", scope="global")
+datastore = experience.get_data_store("data-store-name", scope="global")
 
 # sets the key 'key-name' to 68 and provides users and metadata
 # DataStore.set does not return the value or an EntryInfo object, instead it returns a EntryVersion object.
@@ -52,49 +52,45 @@ datastore.remove("key-name")
 ```
 
 ### Publishing To Message Service
-**NOTE: Messages published with Open Cloud only arrive in live game servers and not in Studio, so you'll have to publish the place to test this.**
+**NOTE: Messages published with Open Cloud only arrive in live game servers and not in Studio.**
 ```py
+import rblxopencloud
+
+# create an Experience object with your experience ID and your api key
+# TODO: replace '13058' with your experience ID
+experience = rblxopencloud.Experience(13058, api_key="api-key-from-step-2")
+
 # publish a message with the topic 'topic-name'
-universe.publish_message("topic-name", "Hello World!")
+experience.publish_message("topic-name", "Hello World!")
 ```
 
-### Publish or Save a `.rbxl` File
-**NOTE: [Place Publishing](#publish-or-save-a-rbxl-file) isn't included in this example due to it requiring an `.rbxl` file.**
+### Uploading Assets
+**NOTE: Only `Decal`, `Audio`, and `Model` (fbx) are supported right now.**
 ```py
-#open the .rbxl file as read bytes
-with open("path-to/place-file.rbxl", "rb") as file:
-    # the first number is the place ID to update, and publish denotes wether to publish or save the place.
-    # TODO: replace '1818' with your place ID
-    universe.upload_place(1818, file, publish=False)
+import rblxopencloud
+
+# create an User object with your user ID and your api key
+# TODO: replace '13058' with your user ID
+user = rblxopencloud.User(13058, api_key="api-key-from-step-2")
+# or, create a Group object:
+group = rblxopencloud.Group(13058, api_key="api-key-from-step-2")
+
+# this example is for uploading a decal:
+with open("path-to/file-object.png", "rb") as file:
+    user.upload_asset(file, rblxopencloud.AssetType.Decal, "name", "description")
+
+# this will wait until Roblox has processed the upload
+if isinstance(asset, rblxopencloud.Asset):
+    # if it's already been processed, then print the asset.
+    print(asset)
+else:
+    # otherwise, we'll go into a loop that continuosly checks if it's done.
+    while True:
+        # this will try to check if the asset has been processed yet
+        operation = asset.fetch_operation()
+        if operation:
+            # if it has been print it then stop the loop.
+            print(operation)
+            break
 ```
-## Final Result (a.k.a copy and paste section)
-```py
-# create a Universe object with your universe/experience ID and your api key
-# TODO: replace '13058' with your universe ID
-universe = rblxopencloud.Universe(13058, api_key="api-key-from-step-2")
-
-# get the data store, using the data store name and scope (defaults to global)
-datastore = universe.get_data_store("data-store-name", scope="global")
-
-# sets the key 'key-name' to 68 and provides users and metadata
-# DataStore.set does not return the value or an EntryInfo object, instead it returns a EntryVersion object.
-datastore.set("key-name", 68, users=[287113233], metadata={"key": "value"})
-
-# get the value with the key 'number'
-# info is a EntryInfo object which contains data like the version code, metadata, userids and timestamps.
-value, info = datastore.get("key-name")
-
-print(value, info)
-
-# increments the key 'key-name' by 1 and ensures to keep the old users and metadata
-# DataStore.increment retuens a value and info pair, just like DataStore.get and unlike DataStore.set
-value, info = datastore.increment("key-name", 1, users=info.users, metadata=info.metadata)
-
-print(value, info)
-
-# deletes the key
-datastore.remove("key-name")
-
-# publish a message with the topic 'topic-name'
-universe.publish_message("topic-name", "Hello World!")
-```
+Examples for more APIs are avalible in the [examples](https://github.com/TreeBen77/rblx-open-cloud/tree/main/examples) directory.

docs/source/creator.rst

@@ -0,0 +1,161 @@
+Creator
+=============================
+
+.. currentmodule:: rblx-open-cloud
+
+.. class:: Creator()
+
+    Class for interacting with the API to upload assets to a user or group.
+
+    .. versionadded:: 1.1
+
+    .. warning::
+
+        This class is not designed to be created by users. It a inherited by :class:`rblx-open-cloud.User` and :class:`rblx-open-cloud.Group`.
+
+    .. attribute:: id 
+
+        The Creator's ID
+
+        :type: int
+
+    .. method:: upload_asset(file, asset_type, name, description, expected_robux_price=0)
+
+        Uploads an asset onto Roblox.
+
+        :param io.BytesIO file: The file opened in bytes to be uploaded.
+        :param rblx-open-cloud.AssetType asset_type: The type of asset you're uploading.
+        :param str name: The name of your asset.
+        :param str description: The description of your asset.
+        :param str expected_robux_price: The amount of robux expected to upload. Fails if lower than actual price.
+
+        :returns: Union[:class:`rblx-open-cloud.Asset`, :class:`rblx-open-cloud.PendingAsset`]
+        :raises rblx-open-cloud.InvalidAsset: The file is not a supported, or is corrupted
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to read and write assets.
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's servers are currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+        .. danger::
+
+            Assets uploaded with Open Cloud can still get your account banned if they're inappropriate.
+
+        .. note::
+
+            Only ``Decal``, ``Audio``, and ``Model`` (as ``fbx``) are supported right now.
+
+    .. method:: update_asset(asset_id, file)
+
+        Updates an existing asset on Roblox.
+
+        :param int asset_id: The ID of the asset to update.
+        :param io.BytesIO file: The file opened in bytes to be uploaded.
+
+        :returns: Union[:class:`rblx-open-cloud.Asset`, :class:`rblx-open-cloud.PendingAsset`]
+        :raises rblx-open-cloud.InvalidAsset: The file is not a supported, or is corrupted
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to read and write assets.
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's servers are currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+        .. danger::
+
+            Assets uploaded with Open Cloud can still get your account banned if they're inappropriate.
+
+        .. note::
+
+            Only ``Model`` (as ``fbx``) can be updated right now.
+
+.. class:: Asset()
+
+    Contains data about an asset, such as it's id, name, and type.
+
+    .. versionadded:: 1.1
+
+    .. warning::
+
+        This class is not designed to be created by users. It is returned by :meth:`Creator.upload_asset` and :meth:`Creator.update_asset`.
+
+    .. attribute:: id 
+
+        The asset's ID
+
+        :type: int
+
+    .. attribute:: name 
+
+        The asset's name
+
+        :type: str
+
+    .. attribute:: description 
+
+        The asset's description
+
+        :type: str
+
+    .. attribute:: creator 
+
+        The asset's creator
+
+        :type: Union[:class:`rblx-open-cloud.Creator`, :class:`rblx-open-cloud.User`, :class:`rblx-open-cloud.Group`]
+
+    .. attribute:: revision_id 
+
+        The ID of the asset's current version/revision
+
+        :type: Optional[int]
+
+    .. attribute:: revision_time
+
+        The time the asset was last update
+
+        :type: Optional[datetime.datetime]
+
+    .. attribute:: type 
+
+        The asset's type
+
+        :type: :class:`rblx-open-cloud.AssetType`
+
+.. class:: PendingAsset()
+
+    Class for assets which aren't processed yet.
+
+    .. versionadded:: 1.1
+
+    .. warning::
+
+        This class is not designed to be created by users. It is returned by :meth:`Creator.upload_asset` and :meth:`Creator.update_asset`.
+
+    .. method:: fetch_operation()
+
+        Fetches the asset info, if completed processing.
+
+        :returns: Optional[:class:`rblx-open-cloud.Asset`]
+        :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to read and write assets.
+        :raises rblx-open-cloud.RateLimited: You're being rate limited by Roblox. Try again in a minute.
+        :raises rblx-open-cloud.ServiceUnavailable: Roblox's servers are currently experiencing downtime.
+        :raises rblx-open-cloud.rblx_opencloudException: Roblox's response was unexpected.
+
+.. class:: AssetType()
+
+    Enum to denote what type an asset is.
+
+    .. versionadded:: 1.1
+
+    .. attribute:: Unknown 
+
+        An unknown asset type (e.g. an unimplemented type)
+
+    .. attribute:: Decal 
+
+        An decal asset type
+
+    .. attribute:: Audio 
+
+        An audio asset type
+
+    .. attribute:: Model 
+
+        An model asset type (fbx)

docs/source/datastore.rst

@@ -9,7 +9,7 @@ Data Store
 
     .. warning::
 
-        This class is not designed to be created by users. It is returned by :meth:`Universe.get_data_store` and :meth:`Universe.list_data_stores`.
+        This class is not designed to be created by users. It is returned by :meth:`Experience.get_data_store` and :meth:`Experience.list_data_stores`.
 
     .. attribute:: name 
 
@@ -19,13 +19,13 @@ Data Store
 
         :type: Union[str, None]
 
-    .. attribute:: universe 
+    .. attribute:: experience 
 
-        :type: rblx-open-cloud.Universe
+        :type: rblx-open-cloud.Experience
 
     .. attribute:: created 
 
-        The data store's creation timestamp, could be ``None`` if not retrieved by :meth:`Universe.list_data_stores`.
+        The data store's creation timestamp, could be ``None`` if not retrieved by :meth:`Experience.list_data_stores`.
 
         :type: Union[datetime.datetime, None]
 

docs/source/exceptions.rst

@@ -37,4 +37,8 @@ Exceptions
 
          The key metadata.
 
-         :type: :class:`rblx-open-cloud.EntryInfo`
+         :type: :class:`rblx-open-cloud.EntryInfo`
+
+.. exception:: InvalidAsset()
+
+   The asset you upload is the wrong type, or is corrupted.

docs/source/universe.rst → docs/source/experience.rst

@@ -1,18 +1,18 @@
-Universe
+Experience
 =============================
 
 .. currentmodule:: rblx-open-cloud
 
-.. class:: Universe(id, api_key)
+.. class:: Experience(id, api_key)
 
-   Class for interacting with the API for a specific universe.
+   Class for interacting with the API for a specific experience.
 
-   :param int id: A Universe ID. Read How to find yours here: `Publishing Places with API Keys <https://create.roblox.com/docs/open-cloud/publishing-places-with-api-keys>`__
+   :param int id: A Experience ID. Read How to find yours here: `Publishing Places with API Keys <https://create.roblox.com/docs/open-cloud/publishing-places-with-api-keys>`__
    :param str api_key: An API key created from `Creator Dashboard <https://create.roblox.com/credentials>`__. *this should be kept safe, as anyone with the key can use it!*
 
    .. attribute:: id 
 
-      The universe's ID
+      The Experience's ID
 
       :type: int
 
@@ -30,22 +30,22 @@ Universe
 
    .. method:: list_data_stores(prefix="", scope="global")
 
-         Returns an Iterable of all :class:`rblx-open-cloud.DataStore` in the Universe which includes :attr:`rblx-open-cloud.DataStore.created`, optionally matching a prefix.
+         Returns an Iterable of all :class:`rblx-open-cloud.DataStore` in the Experience which includes :attr:`rblx-open-cloud.DataStore.created`, optionally matching a prefix.
 
          Lua equivalent: `DataStoreService:ListDataStoresAsync() <https://create.roblox.com/docs/reference/engine/classes/DataStoreService#ListDataStoresAsync>`__
 
          The example below would iterate through every datastore
 
          .. code:: py
 
-            for datastore in universe.list_data_stores():
+            for datastore in experience.list_data_stores():
                 print(datastore.name)
         
          You can simply convert it to a list by putting it in the list function:
 
          .. code:: py
 
-            list(universe.list_data_stores())
+            list(experience.list_data_stores())
          
          :param str prefix: Only Iterates datastores with that start with this string
          :param Union[None, int] limit: Will not return more datastores than this number. Set to ``None`` for no limit.
@@ -94,7 +94,7 @@ Universe
 
          :param int place_id: The place ID to update
          :param io.BytesIO file: The file to send. should be opened as bytes.
-         :param publish bool: Wether to publish the place or just save it.
+         :param bool publish: Wether to publish the place or just save it.
          :returns: :class:`int`
          :raises rblx-open-cloud.InvalidToken: The token is invalid or doesn't have sufficent permissions to upload places.
          :raises rblx-open-cloud.NotFound: The place ID is invalid