From 4ccd124c41e39a23878f5dab54ff8ff5fde757e5 Mon Sep 17 00:00:00 2001 From: nuwang <2070605+nuwang@users.noreply.github.com> Date: Thu, 9 Feb 2023 19:04:31 +0530 Subject: [PATCH] Add more interface docs, regenerate client schema --- client/src/schema/schema.ts | 10 ++-- lib/galaxy/files/sources/__init__.py | 74 +++++++++++++++++++++++++--- packages/package.Makefile | 2 +- 3 files changed, 73 insertions(+), 13 deletions(-) diff --git a/client/src/schema/schema.ts b/client/src/schema/schema.ts index 02e2fde8921..df77c61c635 100644 --- a/client/src/schema/schema.ts +++ b/client/src/schema/schema.ts @@ -520,7 +520,7 @@ export interface paths { }; "/api/histories/{history_id}/contents/{id}": { /** - * Return detailed information about an HDA within a history. + * Return detailed information about an HDA within a history. ``/api/histories/{history_id}/contents/{type}s/{id}`` should be used instead. * @deprecated * @description Return detailed information about an `HDA` or `HDCA` within a history. * @@ -528,7 +528,7 @@ export interface paths { */ get: operations["history_content_api_histories__history_id__contents__id__get"]; /** - * Updates the values for the history content item with the given ``ID``. + * Updates the values for the history content item with the given ``ID``. ``/api/histories/{history_id}/contents/{type}s/{id}`` should be used instead. * @deprecated * @description Updates the values for the history content item with the given ``ID``. */ @@ -3097,10 +3097,10 @@ export interface components { * @default [] * @example [ * { + * "browsable": true, * "doc": "Galaxy's library import directory", * "id": "_import", * "label": "Library Import Directory", - * "listable": true, * "type": "gximport", * "uri_root": "gximport://", * "writable": false @@ -10606,7 +10606,7 @@ export interface operations { }; history_content_api_histories__history_id__contents__id__get: { /** - * Return detailed information about an HDA within a history. + * Return detailed information about an HDA within a history. ``/api/histories/{history_id}/contents/{type}s/{id}`` should be used instead. * @deprecated * @description Return detailed information about an `HDA` or `HDCA` within a history. * @@ -10659,7 +10659,7 @@ export interface operations { }; update_api_histories__history_id__contents__id__put: { /** - * Updates the values for the history content item with the given ``ID``. + * Updates the values for the history content item with the given ``ID``. ``/api/histories/{history_id}/contents/{type}s/{id}`` should be used instead. * @deprecated * @description Updates the values for the history content item with the given ``ID``. */ diff --git a/lib/galaxy/files/sources/__init__.py b/lib/galaxy/files/sources/__init__.py index 63a8b765b72..d369fcfe429 100644 --- a/lib/galaxy/files/sources/__init__.py +++ b/lib/galaxy/files/sources/__init__.py @@ -4,7 +4,6 @@ import time from typing import ( Any, ClassVar, - List, Optional, Set, TYPE_CHECKING, @@ -33,6 +32,12 @@ if TYPE_CHECKING: class FilesSourceProperties(TypedDict): + """Initial set of properties used to initialize a filesource. + + Filesources can extend this typed dict to define any additional + filesource specific properties. + """ + file_sources_config: NotRequired["ConfiguredFileSourcesConfig"] id: NotRequired[str] label: NotRequired[str] @@ -48,29 +53,69 @@ class FilesSourceProperties(TypedDict): class FilesSourceOptions: + """Options to control behaviour of filesource operations, such as realize_to and write_from""" + + # Property overrides for values initially configured through the constructor. For example + # the HTTPFilesSource passes in additional http_headers through these properties, which + # are merged with constructor defined http_headers. The interpretation of these properties + # are filesystem specific. extra_props: Optional[FilesSourceProperties] class SingleFileSource(metaclass=abc.ABCMeta): + """ + Represents a protocol handler for a single remote file that can be read by or written to by Galaxy. + A remote file source can typically handle a url like `https://galaxyproject.org/myfile.txt` or + `drs://myserver/123456`. The filesource abstraction allows programmatic control over the specific source + to access, injection of credentials and access control. Filesources are typically listed and configured + through `file_sources_conf.yml` or programmatically, as required. + + Filesources can be contextualized with a `user_context`, which contains information related to the current + user attempting to access that filesource such as the username, preferences, roles etc., which can then + be used by the filesource to make authorization decisions or inject credentials. + + Filesources are loaded through Galaxy's plugin system in `galaxy.util.plugin_config`. + """ + @abc.abstractmethod def get_writable(self) -> bool: - """Return a boolean indicating if this target is writable.""" + """Return a boolean indicating whether this target is writable.""" @abc.abstractmethod def user_has_access(self, user_context) -> bool: - """Return a boolean indicating if the user can access the FileSource.""" + """Return a boolean indicating whether the user can access the FileSource.""" @abc.abstractmethod def realize_to( self, source_path: str, native_path: str, user_context=None, opts: Optional[FilesSourceOptions] = None ): - """Realize source path (relative to uri root) to local file system path.""" + """Realize source path (relative to uri root) to local file system path. + + :param source_path: url of the source file to copy from. e.g. `https://galaxyproject.org/myfile.txt` + :type source_path: str + :param native_path: local path to write to. e.g. `/tmp/myfile.txt` + :type native_path: str + :param user_context: A user context , defaults to None + :type user_context: FileSourceDictifiable, optional + :param opts: A set of options to exercise additional control over the realize_to method. Filesource specific, defaults to None + :type opts: Optional[FilesSourceOptions], optional + """ @abc.abstractmethod def write_from( self, target_path: str, native_path: str, user_context=None, opts: Optional[FilesSourceOptions] = None ): - """Write file at native path to target_path (relative to uri root).""" + """Write file at native path to target_path (relative to uri root). + + :param target_path: url of the target file to write to within the filesource. e.g. `gxfiles://myftp1/myfile.txt` + :type target_path: str + :param native_path: The local file to read. e.g. `/tmp/myfile.txt` + :type native_path: str + :param user_context: A user context , defaults to None + :type user_context: _type_, optional + :param opts: A set of options to exercise additional control over the write_from method. Filesource specific, defaults to None + :type opts: Optional[FilesSourceOptions], optional + """ @abc.abstractmethod def score_url_match(self, url: str) -> int: @@ -94,6 +139,11 @@ class SingleFileSource(metaclass=abc.ABCMeta): https://cloudstor.aarnet.edu.au/plus/remote.php/webdav/myfolder/myfile.txt, as it can handle only the scheme part of the url. A webdav handler may return a score of 55 for the same url, as both the webdav url and root combined are a specific match. + + :param url: The url to score for a match against this filesource. + :type url: str + :return: A score based on the aforementioned rules. + :rtype: int """ @abc.abstractmethod @@ -113,6 +163,14 @@ class SingleFileSource(metaclass=abc.ABCMeta): class SupportsBrowsing(metaclass=abc.ABCMeta): + """An interface indicating that this filesource is browsable. + + Browsable filesources will typically have a root uri from which to start browsing. + e.g. In an s3 bucket, the root uri may be gxfiles://bucket1/ + + They will also have a list method to list files in a specific path within the filesource. + """ + @abc.abstractmethod def get_uri_root(self) -> str: """Return a prefix for the root (e.g. gxfiles://prefix/).""" @@ -123,9 +181,11 @@ class SupportsBrowsing(metaclass=abc.ABCMeta): class FilesSource(SingleFileSource, SupportsBrowsing): - """ """ + """Represents a combined interface for single or browsable filesources. + The `get_browsable` method can be used to determine whether the filesource is browsable and + implements the `SupportsBrowsing` interface. + """ - # TODO: off-by-default @abc.abstractmethod def get_browsable(self) -> bool: """Return true if the filesource implements the SupportsBrowsing interface.""" diff --git a/packages/package.Makefile b/packages/package.Makefile index dff6b157a68..d44f4d7aac7 100644 --- a/packages/package.Makefile +++ b/packages/package.Makefile @@ -93,4 +93,4 @@ push-release: release: release-local push-release mypy: - mypy . + mypy . --enable-incomplete-feature=Unpack