squarecloud-api 2.0.0

Author: robert-nogueira

README.md

@@ -1,192 +1,50 @@
 [SquareCloud]: https://squarecloud.app
 
-[API]: https://docs.squarecloud.app/api/introducao
+[SquareCloudAPI]: https://docs.squarecloud.app/api/introducao
 
 [@alma]: https://github.com/Robert-Nogueira
 
 # squarecloud-api
 
-squarecloud-api is a wrapper of the [API] of [SquareCloud] made by [@alma]
+squarecloud-api is a wrapper for the [SquareCloudAPI] mainted by [@alma]
+
 
 ## Installing
 
 ````
 pip install squarecloud-api
 ````
 
-## Starting
 
-### Where to get my api key?
+## Getting api key
 
 to get your api key/token just go to the [SquareCloud] website and
 register/login, after that go
 to `dashboard` > `my account` > `Regenerate API/CLI KEY` and copy the key.
 
-### The client instance
-
-with the client you can get information about your application
-
-````python
-import squarecloud as square
-
-client = square.Client(api_key='API KEY')
-
-app_id = 'application id'
-
-
-async def example():
-    logs = await client.get_logs(app_id)
-    print(logs)
-
-    complete_logs = await client.get_logs(app_id)
-    print(complete_logs)
-
-    status = await client.app_status(app_id)
-    print(status.ram)
-    print(status.cpu)
-    print(status.requests)
-    print(status.network)
-    print(status.running)
-    print(status.storage)
-
-````
-
-you can also manage your application
-
-````python
-import squarecloud as square
-
-# you can define if you want debug logs to be shown or not
-# this value by default is True
-client = square.Client(api_key='API KEY')
-
-app_id = 'application id'
-
-
-async def example():
-    await client.backup(app_id)
-    await client.start_app(app_id)
-    await client.stop_app(app_id)
-    await client.restart_app(app_id)
-    await client.delete_app(app_id)
-    await client.commit(app_id, file=square.File('path/to/your/file'))
-
-````
-
-### Application object
-
-Using the client you can also get an application or a list of applications and
-use them to manage your application.
+> ## [Documentation](docs/)
+> - [application](docs/application.md)
+> - [capture_listeners](docs/capture_listeners.md)
+> - [client](docs/client.md)
+> - [commit_and_upload](docs/commit_and_upload.md)
+> - [request_listeners](docs/request_listeners.md)
 
-````python
+## Basict usage
+```python
 import squarecloud as square
+import asyncio
 
-client = square.Client(api_key='API KEY')
-
-
-async def example():
-    app = await client.app('application id')
+client = square.Client('API_KEY', debug=True)
 
-    # app information
-    status = await app.status()
+async def main():
+    status = await client.app_status(app_id='application_id')
+    print(status)
     print(status.ram)
     print(status.cpu)
-    print(status.requests)
-    print(status.network)
-    print(status.running)
-    print(status.storage)
-
-    # managing
-    await app.stop()
-    await app.start()
-    await app.restart()
-    await app.backup()
-    await app.delete()
-    await app.backup()
-    await app.commit(square.File('path/to/your/file'))
-
-    apps_list = await client.all_apps()
-    for app in apps_list:
-        print(app)
-
-````
-
-### Uploading an application
-
-to upload an application you need of a zip contain the following files:
-
-- the main file: the file responsible to start the application
-- the dependency file: contains information about with dependencies need to be
-  installed
-- the configuration file(squarecloud.app): a configuration file to upload, for
-  more information take a look at [this link](https://docs.squarecloud.app/suporte/como-hospedar#configurando-sua-aplicacao)
-
-```python
-import squarecloud as square
-
-client = square.Client(api_key='API KEY')
 
-
-async def example():
-    await client.upload_app(square.File('path/to/my_file.zip'))
-```
-for your convenience a function was added to create the configuration file
-
-```python
-import squarecloud as square
-
-# application example
-square.create_config_file(
-    path='directory/to/save/', # the path where the file should be saved
-    display_name='an cool name',
-    description='an cool description',
-    main='main.py',
-    memory=100,
-    version='recommended',
-)
-
-# website example
-square.create_config_file(
-    path='directory/to/save',
-    display_name='cool website',
-    description='this is really cool',
-    main='index.js',
-    subdomain='coolwebsite.squareweb.app',
-    start='start this cool website', # if not static it is configurable
-    memory=512,
-    version='recommended',
-)
-
-"""
-[REQUIRED] parameters
----------------------
-path: str
-display_name: str
-main: str
-memory: int
-version: Literal['recommended', 'latest']
-
-[OPTIONAL] parameters
----------------------
-avatar: str | None = None
-description: str | None = None
-subdomain: str | None = None
-start: str | None = None
-"""
+asyncio.run(main())
 ```
 
-
-### Debug mode
-Every time a request is made logs are displayed in the terminal containing
-useful information, You can disable this by setting the `debug` parameter to
-False for the client, this value by default is True.
-
-````py
-import squarecloud as square
-
-client = square.Client(api_key='API KEY', debug=False)  # no logs
-````
-
 ## License
 
 MIT License

docs/application.md

@@ -0,0 +1,68 @@
+### Application object
+
+Using the client you can also get an application or a list of applications and
+use them to manage your application.
+
+````python
+import squarecloud as square
+
+client = square.Client(api_key='API KEY')
+
+
+async def example():
+    app = await client.app('application id')
+
+    # app information
+    status = await app.status()  # StatusData(...)
+
+    print(status.ram)  # '70MB'
+    print(status.cpu)  # '5%'
+    print(status.requests)  # 0
+    print(status.network)  # {'total': '0 KB ↑ 0 KB ↓', 'now': '0 KB ↑ 0 KB ↓'}
+    print(status.running)  # True | False
+    print(status.storage)  # '0MB'
+
+    # managing
+    start = await app.start()  # Response(success)
+    stop = await app.stop()  # Response(success)
+    restart = await app.restart()  # Response(success)
+
+    backup = await app.backup()  # BackupData(downloadURL='https://squarecloud.app/dashboard/backup/123.zip')
+    print(
+        backup.downloadURL)  # 'https://squarecloud.app/dashboard/backup/123.zip'
+
+    # [WARNING] this will delete your app, remember to have some backup saved
+    delete = await app.delete()  # Response(success)
+
+    apps_list = await client.all_apps()
+    for app in apps_list:
+        print(app)  # <Application tag='my_cool_bot' id='12345678abcde'>
+````
+
+___
+
+## Caching
+
+When a request is made it returns information from the application and caches
+it in the application itself. In case you need to access this information again
+in a considerable amount of time, that is, if it is not worth making a new
+request to have updated data. In cases like this you can
+access `Application.cache`
+```python
+import squarecloud as square
+from squarecloud.app import Application
+
+client = square.Client('API_KEY')
+
+async def example():
+    def print_cache(app: Application):
+        cache = app.cache
+        print(cache.status)
+        print(cache.logs)
+        print(cache.full_logs)
+        print(cache.backup)
+    
+    app = await client.app('application_id')
+    await app.status()
+    print_cache(app)
+```

docs/capture_listeners.md

@@ -0,0 +1,56 @@
+# Capture Listeners
+
+_this implementation is based on a [suggestion](https://github.com/squarecloudofc/wrapper-api-py/pull/1) made
+by [@Mudinho](https://github.com/zRickz), thanks for contributing_
+
+Sometimes it's very useful to have listeners, with them, you can implement
+features that need to be called whenever "something" is done in your
+application.
+
+For example, imagine that every time a request for the '/logs' route is made,
+my application executes some task that checks if the new logs are different
+from the old ones. Well, let's see how this could be done:
+
+```python
+import squarecloud as square
+from squarecloud import Endpoint
+
+client = square.Client('API_KEY', debug=False)
+apps = await client.all_apps()
+app = apps[0]
+
+
+@app.capture(endpoint=Endpoint.logs())
+async def on_logs_request(before, after):
+    if after != before:
+        print(f'New logs!!! {after}')
+
+
+async def example():
+    await app.logs()  # True
+    await app.logs()  # False
+    await app.logs(avoid_listener=True)  # the listener is not called
+```
+
+As you may have noticed, the first time the comparison between the logs
+happens `after != before` returns `True`, this happens precisely
+because `after` is equal to `LogsData(logs=None)`, as there is nothing yet
+stored in internal cache.
+
+**Another information about this decorator**
+
+- if you use discord.py or some fork (most likely you do), you should
+  be familiar with the fact that what differentiates events is the name
+  of the functions that the decorator involves, but here it differs, to know
+  which
+  api route the decorator needs to "watch" the endpoint parameter is used which
+  takes an `Endpoint` class, so the name of the function that the decorator
+  wraps
+  It's up to you.
+- the function that the decorator wraps can actually be anything you
+  be a callable. This includes normal functions, coroutines, and even
+  classes(`__init__` will be called)
+- if the endpoint is not an `Endpoint.app_status()`
+  , `Endpoints.logs()`, `Endpoints.full_logs()` or `Endpoints.backup()`
+  only one `response` parameter (of type `squarecloud.http.Response`) will be
+  returned