Generate API Schema

jupyter_fsspec/api_schema.yml

@@ -0,0 +1,227 @@
+openapi: 3.1.0
+info:
+  title: jupyter-fsspec API
+  version: 0.4.0
+paths:
+  /jupyter_fsspec/config:
+    get:
+      description: List all source filesystems in configuration file
+      operationId: listConfigSources
+      responses:
+        '200':
+          description: Retrieved available filesystems from configuration file.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Config'
+components:
+  schemas:
+    BaseRequest:
+      properties:
+        key:
+          type: string
+          title: Filesystem name
+          description: Unique identifier given as the filesystem 'name' in the config
+            file
+        item_path:
+          type: string
+          title: Path
+          description: Acting path in filesystem
+      type: object
+      required:
+      - key
+      - item_path
+      title: BaseRequest
+      description: 'The required information for all Filesystem handler endpoints.
+
+
+        key: unique
+
+        item_path: destination path for the acting filesystem'
+    DeleteRequest:
+      properties:
+        key:
+          type: string
+          title: Filesystem name
+          description: Unique identifier given as the filesystem 'name' in the config
+            file
+        item_path:
+          type: string
+          title: Path
+          description: Acting path in filesystem
+      type: object
+      required:
+      - key
+      - item_path
+      title: DeleteRequest
+      description: 'Placeholder model for delete request
+
+
+        No additional information is needed than base request'
+    Direction:
+      type: string
+      enum:
+      - upload
+      - download
+      title: Direction
+    GetRequest:
+      properties:
+        key:
+          type: string
+          title: Filesystem name
+          description: Unique identifier given as the filesystem 'name' in the config
+            file
+        item_path:
+          type: string
+          title: Path
+          description: Acting path in filesystem
+        type:
+          anyOf:
+          - $ref: '#/components/schemas/RequestType'
+          - type: 'null'
+          title: Type of GET request
+          description: Either a 'range' GET request for file or 'default' for normal
+            GET
+          default: default
+      type: object
+      required:
+      - key
+      - item_path
+      title: GetRequest
+      description: 'GET request specific items.
+
+
+        type: option to specify type of GET request'
+    PostRequest:
+      properties:
+        key:
+          type: string
+          title: Filesystem name
+          description: Unique identifier given as the filesystem 'name' in the config
+            file
+        item_path:
+          type: string
+          title: Path
+          description: Acting path in filesystem
+        content:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: File content or file/directory name
+          description: Content to be created upon request
+        action:
+          anyOf:
+          - $ref: '#/components/schemas/RequestAction'
+          - type: 'null'
+          title: Move or copy action indicator
+          description: Specify 'move' action when calling action handler, default
+            treated as copy
+      type: object
+      required:
+      - key
+      - item_path
+      title: PostRequest
+      description: 'POST request specific items.
+
+
+        content: content to be created upon request
+
+        action: move action specified when calling action handler'
+    RequestAction:
+      type: string
+      const: move
+      title: RequestAction
+    RequestType:
+      type: string
+      enum:
+      - default
+      - range
+      title: RequestType
+    TransferRequest:
+      properties:
+        key:
+          type: string
+          title: Source filesystem name
+          description: Unique identifier given as the filesystem 'name' in the config
+            file
+        destination_key:
+          type: string
+          title: Destination filesystem name
+          description: Unique identifier given as the filesystem 'name' in the config
+            file
+        local_path:
+          type: string
+          title: Local Path
+        remote_path:
+          type: string
+          title: Remote Path
+        action:
+          allOf:
+          - $ref: '#/components/schemas/Direction'
+          title: Transfer direction
+          description: Can be 'upload' or 'download for local to remote or remote
+            to local respectively
+      type: object
+      required:
+      - key
+      - destination_key
+      - local_path
+      - remote_path
+      - action
+      title: TransferRequest
+      description: 'Requests made to download, upload and sync.
+
+
+        key: unique
+
+        destination_key: unique
+
+        local_path: file/directory path, filesystem root path for sync
+
+        remote_path: file/directory path, filesystem root path for sync
+
+        action: enum option upload or download'
+    Config:
+      properties:
+        sources:
+          items:
+            $ref: '#/components/schemas/Source'
+          type: array
+          title: Sources
+      type: object
+      required:
+      - sources
+      title: Config
+      description: A list of source filesystem configurations
+    Source:
+      properties:
+        name:
+          type: string
+          title: Name
+        path:
+          type: string
+          title: Path
+        protocol:
+          anyOf:
+          - type: string
+          - type: 'null'
+          title: Protocol
+        args:
+          anyOf:
+          - items: {}
+            type: array
+          - type: 'null'
+          title: Args
+          default: []
+        kwargs:
+          anyOf:
+          - type: object
+          - type: 'null'
+          title: Kwargs
+          default: {}
+      type: object
+      required:
+      - name
+      - path
+      title: Source
+      description: Filesystem configurations passed to fsspec

jupyter_fsspec/file_manager.py

@@ -1,6 +1,5 @@
 from jupyter_core.paths import jupyter_config_dir
-from pydantic import BaseModel
-from typing import Optional, Dict, List
+from .models import Source, Config
 from fsspec.utils import infer_storage_options
 from fsspec.implementations.asyn_wrapper import AsyncFileSystemWrapper
 import fsspec
@@ -16,18 +15,6 @@
 logger.setLevel(logging.INFO)
 
 
-class Source(BaseModel):
-    name: str
-    path: str
-    protocol: Optional[str] = None
-    args: Optional[List] = []
-    kwargs: Optional[Dict] = {}
-
-
-class Config(BaseModel):
-    sources: List[Source]
-
-
 class FileSystemManager:
     def __init__(self, config_file):
         self.filesystems = {}

jupyter_fsspec/handlers.py

@@ -1,7 +1,7 @@
 from .file_manager import FileSystemManager
 from jupyter_server.base.handlers import APIHandler
 from jupyter_server.utils import url_path_join
-from .schemas import GetRequest, PostRequest, DeleteRequest, TransferRequest, Direction
+from .models import GetRequest, PostRequest, DeleteRequest, TransferRequest, Direction
 from .utils import parse_range
 from .exceptions import ConfigFileException
 from contextlib import contextmanager

jupyter_fsspec/models.py

@@ -0,0 +1,123 @@
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, List
+from enum import Enum
+
+
+class Source(BaseModel):
+    """Filesystem configurations passed to fsspec"""
+
+    name: str
+    path: str
+    protocol: Optional[str] = None
+    args: Optional[List] = []
+    kwargs: Optional[Dict] = {}
+
+
+class Config(BaseModel):
+    """A list of source filesystem configurations"""
+
+    sources: List[Source]
+
+
+class RequestType(str, Enum):
+    default = "default"
+    range = "range"
+
+
+class RequestAction(str, Enum):
+    move = "move"
+
+
+class BaseRequest(BaseModel):
+    """
+    The required information for all Filesystem handler endpoints.
+
+    key: unique
+    item_path: destination path for the acting filesystem
+    """
+
+    key: str = Field(
+        ...,
+        title="Filesystem name",
+        description="Unique identifier given as the filesystem 'name' in the config file",
+    )
+    item_path: str = Field(..., title="Path", description="Acting path in filesystem")
+
+
+class GetRequest(BaseRequest):
+    """
+    GET request specific items.
+
+    type: option to specify type of GET request
+    """
+
+    type: Optional[RequestType] = Field(
+        default=RequestType.default,
+        title="Type of GET request",
+        description="Either a 'range' GET request for file or 'default' for normal GET",
+    )
+
+
+class PostRequest(BaseRequest):
+    """
+    POST request specific items.
+
+    content: content to be created upon request
+    action: move action specified when calling action handler
+    """
+
+    content: Optional[str] = Field(
+        default=None,
+        title="File content or file/directory name",
+        description="Content to be created upon request",
+    )
+    action: Optional[RequestAction] = Field(
+        default=None,
+        title="Move or copy action indicator",
+        description="Specify 'move' action when calling action handler, default treated as copy",
+    )
+
+
+class DeleteRequest(BaseRequest):
+    """
+    Placeholder model for delete request
+
+    No additional information is needed than base request
+    """
+
+    pass
+
+
+class Direction(str, Enum):
+    UPLOAD = "upload"
+    DOWNLOAD = "download"
+
+
+class TransferRequest(BaseModel):
+    """
+    Requests made to download, upload and sync.
+
+    key: unique
+    destination_key: unique
+    local_path: file/directory path, filesystem root path for sync
+    remote_path: file/directory path, filesystem root path for sync
+    action: enum option upload or download
+    """
+
+    key: str = Field(
+        ...,
+        title="Source filesystem name",
+        description="Unique identifier given as the filesystem 'name' in the config file",
+    )
+    destination_key: str = Field(
+        ...,
+        title="Destination filesystem name",
+        description="Unique identifier given as the filesystem 'name' in the config file",
+    )
+    local_path: str
+    remote_path: str
+    action: Direction = Field(
+        ...,
+        title="Transfer direction",
+        description="Can be 'upload' or 'download for local to remote or remote to local respectively",
+    )