diff --git a/jupyter_fsspec/api_schema.yml b/jupyter_fsspec/api_schema.yml index 12dfe32..7e9e32b 100644 --- a/jupyter_fsspec/api_schema.yml +++ b/jupyter_fsspec/api_schema.yml @@ -1,164 +1,167 @@ +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: - description: 'The required information for all Filesystem handler endpoints. - - - key: unique - - item_path: destination path for the acting filesystem' properties: - item_path: - description: Acting path in filesystem - title: Path - type: string key: + type: string + title: Filesystem name description: Unique identifier given as the filesystem 'name' in the config file - title: Filesystem name + item_path: type: string + title: Path + description: Acting path in filesystem + type: object required: - key - item_path title: BaseRequest - type: object - DeleteRequest: - description: 'Placeholder model for delete request + description: 'The required information for all Filesystem handler endpoints. - No additional information is needed than base request' + key: unique + + item_path: destination path for the acting filesystem' + DeleteRequest: properties: - item_path: - description: Acting path in filesystem - title: Path - type: string key: + type: string + title: Filesystem name description: Unique identifier given as the filesystem 'name' in the config file - title: Filesystem name + item_path: type: string + title: Path + description: Acting path in filesystem + type: object required: - key - item_path title: DeleteRequest - type: object + description: 'Placeholder model for delete request + + + No additional information is needed than base request' Direction: + type: string enum: - upload - download title: Direction - type: string GetRequest: - description: 'GET request specific items. - - - type: option to specify type of GET request' properties: - item_path: - description: Acting path in filesystem - title: Path - type: string key: + type: string + title: Filesystem name description: Unique identifier given as the filesystem 'name' in the config file - title: Filesystem name + item_path: type: string + title: Path + description: Acting path in filesystem type: anyOf: - $ref: '#/components/schemas/RequestType' - type: 'null' - default: default + title: Type of GET request description: Either a 'range' GET request for file or 'default' for normal GET - title: Type of GET request + default: default + type: object required: - key - item_path title: GetRequest - type: object - PostRequest: - description: 'POST request specific items. + description: 'GET request specific items. - content: content to be created upon request - - action: move action specified when calling action handler' + 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' - default: null + title: Move or copy action indicator description: Specify 'move' action when calling action handler, default treated as copy - title: Move or copy action indicator - content: - anyOf: - - type: string - - type: 'null' - default: null - description: Content to be created upon request - title: File content or file/directory name - item_path: - description: Acting path in filesystem - title: Path - type: string - key: - description: Unique identifier given as the filesystem 'name' in the config - file - title: Filesystem name - type: string + type: object required: - key - item_path title: PostRequest - type: object + 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 - type: string RequestType: + type: string enum: - default - range title: RequestType - type: string 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' properties: - action: - allOf: - - $ref: '#/components/schemas/Direction' - description: Can be 'upload' or 'download for local to remote or remote - to local respectively - title: Transfer direction - destination_key: + key: + type: string + title: Source filesystem name description: Unique identifier given as the filesystem 'name' in the config file - title: Destination filesystem name + destination_key: type: string - key: + title: Destination filesystem name description: Unique identifier given as the filesystem 'name' in the config file - title: Source filesystem name - type: string local_path: - title: Local Path type: string + title: Local Path remote_path: - title: 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 @@ -166,8 +169,59 @@ components: - 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 -info: - title: jupyter-fsspec API - version: 0.4.0 -openapi: 3.1.1 + 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 diff --git a/jupyter_fsspec/models.py b/jupyter_fsspec/models.py index 076d030..97c32e3 100644 --- a/jupyter_fsspec/models.py +++ b/jupyter_fsspec/models.py @@ -4,6 +4,8 @@ class Source(BaseModel): + """Filesystem configurations passed to fsspec""" + name: str path: str protocol: Optional[str] = None @@ -12,6 +14,8 @@ class Source(BaseModel): class Config(BaseModel): + """A list of source filesystem configurations""" + sources: List[Source] diff --git a/jupyter_fsspec/scripts/config_schema.py b/jupyter_fsspec/scripts/config_schema.py new file mode 100644 index 0000000..9b7863e --- /dev/null +++ b/jupyter_fsspec/scripts/config_schema.py @@ -0,0 +1,21 @@ +from jupyter_fsspec.models import Config +from pydantic.json_schema import models_json_schema +import yaml + + +def generate_config_schema(): + models = [Config] + _, schemas = models_json_schema( + [(model, "validation") for model in models], + ref_template="#/components/schemas/{model}", + ) + config_schema = { + "info": {"title": "jupyter-fsspec API", "version": "0.4.0"}, + "components": {"schemas": schemas.get("$defs")}, + } + config = yaml.dump(config_schema) + print(config) + + +if __name__ == "__main__": + generate_config_schema() diff --git a/jupyter_fsspec/scripts/update_api_schema.py b/jupyter_fsspec/scripts/update_api_schema.py index eab1001..198f294 100644 --- a/jupyter_fsspec/scripts/update_api_schema.py +++ b/jupyter_fsspec/scripts/update_api_schema.py @@ -1,4 +1,5 @@ from jupyter_fsspec.models import ( + Config, BaseRequest, GetRequest, PostRequest, @@ -6,30 +7,66 @@ TransferRequest, ) from pydantic.json_schema import models_json_schema +from openapi_pydantic.v3 import OpenAPI, Info, PathItem, Operation +from openapi_pydantic.util import PydanticSchema, construct_open_api_with_schema_class import yaml import os -def write_json_schema(models): +def write_json_schema(openapi): + cwd = os.getcwd() + schema_file = os.path.join(cwd, "jupyter_fsspec/api_schema.yml") + + with open(schema_file, "w") as f: + f.write( + yaml.dump( + openapi.model_dump( + by_alias=True, + mode="json", + exclude_none=True, + exclude_unset=True, + ), + sort_keys=False, + ) + ) + + +def base_openapi(models) -> OpenAPI: _, schemas = models_json_schema( [(model, "validation") for model in models], ref_template="#/components/schemas/{model}", ) - open_api_schema = { - "openapi": "3.1.1", - "info": {"title": "jupyter-fsspec API", "version": "0.4.0"}, - "components": {"schemas": schemas.get("$defs")}, - } + return OpenAPI( + openapi="3.1.0", + info=Info(title="jupyter-fsspec API", version="0.4.0"), + components={"schemas": schemas.get("$defs")}, + paths={ + "/jupyter_fsspec/config": PathItem( + get=Operation( + operationId="listConfigSources", + description="List all source filesystems in configuration file", + responses={ + "200": { + "description": "Retrieved available filesystems from configuration file.", + "content": { + "application/json": { + "schema": PydanticSchema(schema_class=Config) + } + }, + } + }, + ) + ), + }, + ) - cwd = os.getcwd() - schema_file = os.path.join(cwd, "jupyter_fsspec/api_schema.yml") - with open(schema_file, "w") as f: - yaml.dump(open_api_schema, f) +open_api = base_openapi( + [BaseRequest, GetRequest, PostRequest, DeleteRequest, TransferRequest] +) +open_api = construct_open_api_with_schema_class(open_api) if __name__ == "__main__": - write_json_schema( - [BaseRequest, GetRequest, PostRequest, DeleteRequest, TransferRequest] - ) + write_json_schema(open_api)