dev 0.0.30 [ci skip]

Signed-off-by: Alexander Piskun <[email protected]>

.run/Skeleton.run.xml

@@ -0,0 +1,29 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="Skeleton" type="PythonConfigurationType" factoryName="Python">
+    <module name="nc_py_api" />
+    <option name="INTERPRETER_OPTIONS" value="" />
+    <option name="PARENT_ENVS" value="true" />
+    <envs>
+      <env name="APP_ID" value="skeleton" />
+      <env name="APP_PORT" value="9030" />
+      <env name="APP_SECRET" value="12345" />
+      <env name="APP_VERSION" value="1.0.0" />
+      <env name="NEXTCLOUD_URL" value="http://nextcloud.local/index.php" />
+      <env name="PYTHONUNBUFFERED" value="1" />
+    </envs>
+    <option name="SDK_HOME" value="" />
+    <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />
+    <option name="IS_MODULE_SDK" value="true" />
+    <option name="ADD_CONTENT_ROOTS" value="true" />
+    <option name="ADD_SOURCE_ROOTS" value="true" />
+    <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/examples/as_app/skeleton/src/main.py" />
+    <option name="PARAMETERS" value="" />
+    <option name="SHOW_COMMAND_LINE" value="false" />
+    <option name="EMULATE_TERMINAL" value="false" />
+    <option name="MODULE_MODE" value="false" />
+    <option name="REDIRECT_INPUT" value="false" />
+    <option name="INPUT_FILE" value="" />
+    <method v="2" />
+  </configuration>
+</component>

.run/to_gif.run.xml → .run/ToGif.run.xml

@@ -1,15 +1,15 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="to_gif" type="PythonConfigurationType" factoryName="Python">
+  <configuration default="false" name="ToGif" type="PythonConfigurationType" factoryName="Python">
     <module name="nc_py_api" />
     <option name="INTERPRETER_OPTIONS" value="" />
     <option name="PARENT_ENVS" value="true" />
     <envs>
-      <env name="PYTHONUNBUFFERED" value="1" />
       <env name="APP_ID" value="to_gif" />
-      <env name="APP_PORT" value="9029" />
+      <env name="APP_PORT" value="9031" />
       <env name="APP_SECRET" value="12345" />
       <env name="APP_VERSION" value="1.0.0" />
       <env name="NEXTCLOUD_URL" value="http://nextcloud.local/index.php" />
+      <env name="PYTHONUNBUFFERED" value="1" />
     </envs>
     <option name="SDK_HOME" value="" />
     <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$" />

.run/register.run.xml → .run/register_nc_py_api.run.xml

@@ -1,15 +1,15 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="register" type="PythonConfigurationType" factoryName="Python">
+  <configuration default="false" name="register_nc_py_api" type="PythonConfigurationType" factoryName="Python">
     <module name="nc_py_api" />
     <option name="INTERPRETER_OPTIONS" value="" />
     <option name="PARENT_ENVS" value="true" />
     <envs>
+      <env name="PYTHONUNBUFFERED" value="1" />
       <env name="APP_ID" value="nc_py_api" />
       <env name="APP_PORT" value="9009" />
       <env name="APP_SECRET" value="12345" />
       <env name="APP_VERSION" value="1.0.0" />
       <env name="NEXTCLOUD_URL" value="http://nextcloud.local/index.php" />
-      <env name="PYTHONUNBUFFERED" value="1" />
     </envs>
     <option name="SDK_HOME" value="" />
     <option name="WORKING_DIRECTORY" value="$PROJECT_DIR$/tests" />

CHANGELOG.md

@@ -2,14 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.0.30 - 2023-08-17]
+## [0.0.30 - 2023-08-15]
 
 ### Added
 
 - `Nextcloud.response_headers` property, to get headers from last response.
+
 ### Changed
 
-- Reworked `External API` declarations, skeleton made much simpler.
+- Reworked skeleton for the applications, added skeleton to examples.
 
 ## [0.0.29 - 2023-08-13]
 

Makefile

@@ -3,6 +3,7 @@
 .PHONY: docs
 .PHONY: html
 docs html:
+	rm -rf docs/_build
 	$(MAKE) -C docs html
 
 .PHONY: help

examples/as_app/skeleton/Makefile

@@ -2,45 +2,45 @@
 
 .PHONY: help
 help:
-	@echo "Welcome to app_python_skeleton example. Please use \`make <target>\` where <target> is one of"
+	@echo "Welcome to Skeleton example. Please use \`make <target>\` where <target> is one of"
 	@echo " "
 	@echo "  Next commands are only for dev environment with nextcloud-docker-dev!"
 	@echo "  They should run from the host you are developing on(with activated venv) and not in the container with Nextcloud!"
 	@echo "  "
 	@echo "  build-push        build image and upload to ghcr.io"
 	@echo "  "
-	@echo "  deploy            deploy example to registered 'docker_dev'"
+	@echo "  deploy            deploy Skeleton to registered 'docker_dev'"
 	@echo "  "
-	@echo "  run28             install app_python_skeleton for Nextcloud 28"
-	@echo "  run27             install app_python_skeleton for Nextcloud 27"
+	@echo "  run28             install Skeleton for Nextcloud 28"
+	@echo "  run27             install Skeleton for Nextcloud 27"
 	@echo "  "
 	@echo "  For development of this example use PyCharm run configurations. Development is always set for last Nextcloud."
-	@echo "  First run 'app_python_skeleton' and then 'make manual_register', after that you can use/debug/develop it and easy test."
+	@echo "  First run 'Skeleton' and then 'make manual_register', after that you can use/debug/develop it and easy test."
 	@echo "  "
-	@echo "  manual_register   perform registration of running 'app_python_skeleton' into 'manual_install' deploy daemon."
+	@echo "  manual_register   perform registration of running Skeleton into the 'manual_install' deploy daemon."
 
 .PHONY: build-push
 build-push:
 	docker login ghcr.io
-	docker buildx build --push --platform linux/arm64/v8,linux/amd64 --tag ghcr.io/cloud-py-api/py_app_v2-skeleton:latest .
+	docker buildx build --push --platform linux/arm64/v8,linux/amd64 --tag ghcr.io/cloud-py-api/skeleton:latest .
 
 .PHONY: deploy
 deploy:
-	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:deploy app_python_skeleton docker_dev \
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:deploy skeleton docker_dev \
 		--info-xml https://raw.githubusercontent.com/cloud-py-api/nc_py_api/main/examples/as_app/skeleton/appinfo/info.xml
 
 .PHONY: run28
 run28:
-	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:unregister app_python_skeleton --silent || true
-	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register app_python_skeleton docker_dev -e --force-scopes
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:unregister skeleton --silent || true
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register skeleton docker_dev -e --force-scopes
 
 .PHONY: run27
 run27:
-	docker exec master-stable27-1 sudo -u www-data php occ app_ecosystem_v2:app:unregister app_python_skeleton --silent || true
-	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register app_python_skeleton docker_dev -e --force-scopes
+	docker exec master-stable27-1 sudo -u www-data php occ app_ecosystem_v2:app:unregister skeleton --silent || true
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register skeleton docker_dev -e --force-scopes
 
 .PHONY: manual_register
 manual_register:
-	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register app_python_skeleton manual_install --json-info \
-  "{\"appid\":\"app_python_skeleton\",\"name\":\"App Python Skeleton\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"host\":\"host.docker.internal\",\"port\":9029,\"scopes\":{\"required\":[],\"optional\":[]},\"protocol\":\"http\",\"system_app\":0}" \
+	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register skeleton manual_install --json-info \
+  "{\"appid\":\"skeleton\",\"name\":\"App Skeleton\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"host\":\"host.docker.internal\",\"port\":9030,\"scopes\":{\"required\":[],\"optional\":[]},\"protocol\":\"http\",\"system_app\":0}" \
   -e --force-scopes

examples/as_app/skeleton/appinfo/info.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0"?>
 <info>
-	<id>app_python_skeleton</id>
-	<name>App Python Skeleton</name>
+	<id>skeleton</id>
+	<name>App Skeleton</name>
 	<summary>Nextcloud Python Application Skeleton</summary>
 	<description>
-	<![CDATA[Example of the Nextcloud application written in python]]>
+	<![CDATA[Simplest skeleton of the Nextcloud application written in python]]>
 	</description>
 	<version>1.0.0</version>
 	<licence>MIT</licence>
@@ -21,7 +21,7 @@
 	<ex-app>
 		<docker-install>
 			<registry>ghcr.io</registry>
-			<image>cloud-py-api/py_app_v2-skeleton</image>
+			<image>cloud-py-api/skeleton</image>
 			<image-tag>latest</image-tag>
 		</docker-install>
 		<scopes>

examples/as_app/skeleton/src/main.py

@@ -5,7 +5,7 @@
 from fastapi import FastAPI
 
 from nc_py_api import NextcloudApp
-from nc_py_api.ex_app import LogLvl, run_app
+from nc_py_api.ex_app import LogLvl, run_app, set_handlers
 
 APP = FastAPI()
 
@@ -23,5 +23,10 @@ def enabled_handler(enabled: bool, nc: NextcloudApp) -> str:
     return ""
 
 
+@APP.on_event("startup")
+def initialization():
+    set_handlers(APP, enabled_handler)
+
+
 if __name__ == "__main__":
-    run_app(APP, enabled_handler, "main:APP", log_level="trace")
+    run_app("main:APP", log_level="trace")

examples/as_app/to_gif/Makefile

@@ -17,7 +17,7 @@ help:
 	@echo "  For development of this example use PyCharm run configurations. Development is always set for last Nextcloud."
 	@echo "  First run 'to_gif' and then 'make manual_register', after that you can use/debug/develop it and easy test."
 	@echo "  "
-	@echo "  manual_register   perform registration of running 'to_gif' into 'manual_install' deploy daemon."
+	@echo "  manual_register   perform registration of running 'to_gif' into the 'manual_install' deploy daemon."
 
 .PHONY: build-push
 build-push:
@@ -42,5 +42,5 @@ run27:
 .PHONY: manual_register
 manual_register:
 	docker exec master-nextcloud-1 sudo -u www-data php occ app_ecosystem_v2:app:register to_gif manual_install --json-info \
-  "{\"appid\":\"to_gif\",\"name\":\"to_gif\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"host\":\"host.docker.internal\",\"port\":9029,\"scopes\":{\"required\":[10],\"optional\":[32]},\"protocol\":\"http\",\"system_app\":0}" \
+  "{\"appid\":\"to_gif\",\"name\":\"to_gif\",\"daemon_config_name\":\"manual_install\",\"version\":\"1.0.0\",\"secret\":\"12345\",\"host\":\"host.docker.internal\",\"port\":9030,\"scopes\":{\"required\":[10],\"optional\":[32]},\"protocol\":\"http\",\"system_app\":0}" \
   -e --force-scopes

nc_py_api/ex_app/__init__.py

@@ -1,5 +1,5 @@
 """All possible ExApp stuff for NextcloudApp that can be used."""
 from .defs import ApiScope, LogLvl
-from .integration_fastapi import nc_app
+from .integration_fastapi import nc_app, set_handlers
 from .ui.files import UiActionFileInfo, UiFileActionHandlerInfo
 from .uvicorn_fastapi import run_app

nc_py_api/ex_app/integration_fastapi.py

@@ -1,4 +1,4 @@
-"""Directly related stuff to FastAPI."""
+"""FastAPI directly related stuff."""
 
 from typing import Annotated, Callable, Optional
 
@@ -19,24 +19,29 @@ def nc_app(request: Request) -> NextcloudApp:
     return nextcloud_app
 
 
-def set_enabled_handler(fast_api_app: FastAPI, callback: Callable[[bool, NextcloudApp], str]):
-    """Sets ``enabled``/``disabled`` applications handlers."""
+def set_handlers(
+    fast_api_app: FastAPI,
+    enabled_handler: Callable[[bool, NextcloudApp], str],
+    heartbeat_handler: Optional[Callable[[], str]] = None,
+):
+    """Defines handlers for the application.
+
+    :param fast_api_app: FastAPI() call return value.
+    :param enabled_handler: ``Required``, callback which will be called for `enabling`/`disabling` app event.
+    :param heartbeat_handler: Optional, callback that will be called for the `heartbeat` deploy event.
+    """
 
     @fast_api_app.put("/enabled")
-    def enabled_handler(
+    def enabled_callback(
         enabled: bool,
         nc: Annotated[NextcloudApp, Depends(nc_app)],
     ):
-        r = callback(enabled, nc)
+        r = enabled_handler(enabled, nc)
         return JSONResponse(content={"error": r}, status_code=200)
 
-
-def enable_heartbeat(fast_api_app: FastAPI, callback: Optional[Callable[[], str]] = None):
-    """Enables ``heartbeat`` application endpoint. **callback** is *Optional*."""
-
     @fast_api_app.get("/heartbeat")
-    def heartbeat_handler():
+    def heartbeat_callback():
         return_status = "ok"
-        if callback is not None:
-            return_status = callback()
+        if heartbeat_handler is not None:
+            return_status = heartbeat_handler()
         return JSONResponse(content={"status": return_status}, status_code=200)

nc_py_api/ex_app/uvicorn_fastapi.py

@@ -2,26 +2,17 @@
 import typing
 from os import environ
 
-from fastapi import FastAPI
 from uvicorn import run
 from uvicorn.config import ASGIApplication
 
-from ..nextcloud import NextcloudApp
-from .integration_fastapi import enable_heartbeat, set_enabled_handler
-
 
 def run_app(
-    fast_api_app: FastAPI,
-    enabled_handler: typing.Callable[[bool, NextcloudApp], str],
     uvicorn_app: typing.Union["ASGIApplication", typing.Callable, str],
-    heartbeat_handler: typing.Optional[typing.Callable[[], str]] = None,
+    *args,
     **kwargs,
 ) -> None:
-    """Runs the application."""
-
-    @fast_api_app.on_event("startup")
-    def initialization():
-        set_enabled_handler(fast_api_app, enabled_handler)
-        enable_heartbeat(fast_api_app, heartbeat_handler)
+    """Wrapper around Uvicorn's ``run`` function.
 
-    run(uvicorn_app, host=environ.get("APP_HOST", "127.0.0.1"), port=int(environ["APP_PORT"]), **kwargs)
+    Accepts and passes all arguments to it, except for ``host`` and ``port`` which are taken from the environment.
+    """
+    run(uvicorn_app, *args, host=environ.get("APP_HOST", "127.0.0.1"), port=int(environ["APP_PORT"]), **kwargs)

tests/_install.py

@@ -31,5 +31,10 @@ def heartbeat_callback():
     return "ok"
 
 
+@APP.on_event("startup")
+def initialization():
+    ex_app.set_handlers(APP, enabled_handler, heartbeat_callback)
+
+
 if __name__ == "__main__":
-    ex_app.run_app(APP, enabled_handler, "_install:APP", heartbeat_callback, log_level="trace")
+    ex_app.run_app("_install:APP", log_level="trace")