girder-client 5.0.6.dev2__tar.gz → 5.0.6.dev10__tar.gz

{girder_client-5.0.6.dev2 → girder_client-5.0.6.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: girder-client
-Version: 5.0.6.dev2
+Version: 5.0.6.dev10
 Summary: Python client for interacting with Girder servers
 Home-page: http://girder.readthedocs.org/en/latest/python-client.html
 Author: Kitware, Inc.

girder_client-5.0.6.dev10/girder_client/_jsonemitter.py

@@ -0,0 +1,268 @@
+"""
+Helper functions used by the CLI. Currently this only defines
+:class:`_JSONEmitter`, which we test here.
+
+Example:
+    >>> from girder_client._jsonemitter import _JSONEmitter
+    >>> import io
+    >>> self = _JSONEmitter(stream=io.StringIO())
+    >>> self.start_dict()
+    >>> self.setitem('version', '1.0.0')
+    >>> self.start_subcontainer('info')
+    >>> self.start_list()
+    >>> self.append({})
+    >>> self.append([{}])
+    >>> self.append({})
+    >>> self.end_list()
+    >>> self.end_dict()
+    >>> text = self.stream.getvalue()
+    >>> # Test that we decode correctly
+    >>> import json as json
+    >>> print(json.loads(text))
+    {'version': '1.0.0', 'info': [{}, [{}], {}]}
+
+Example:
+    >>> from girder_client._jsonemitter import _JSONEmitter
+    >>> import io
+    >>> self = _JSONEmitter(stream=io.StringIO())
+    >>> self.start_dict()
+    >>> self.setitem('key1', 'value1')
+    >>> self.start_subcontainer('subdict1')
+    >>> self.start_dict()
+    >>> self.end_dict()
+    >>> #
+    >>> self.start_subcontainer('subdict2')
+    >>> self.start_dict()
+    >>> self.setitem('subkey1', 'subvalue1')
+    >>> self.setitem('subkey2', 'subvalue2')
+    >>> self.setitem('subkey3', [1, 2, 3, {"a": "a"}])
+    >>> self.end_dict()
+    >>> #
+    >>> self.start_subcontainer('sublist')
+    >>> self.start_list()
+    >>> self.append('sublist_value1')
+    >>> self.append('sublist_value2')
+    >>> self.append([1, 2, 3, {"a": "a"}])
+    >>> self.end_list()
+    >>> #
+    >>> self.setitem('key2', 'value2')
+    >>> self.end_dict()
+    >>> #
+    >>> text = self.stream.getvalue()
+    >>> # Test that we decode correctly
+    >>> import json
+    >>> print(json.dumps(json.loads(text)))
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from typing import Any, Literal, TextIO
+
+__all__ = ['_JSONEmitter']
+
+_ContainerKind = Literal['root', 'dict', 'list']
+
+
+@dataclass
+class _Context:
+    """State for one open JSON container."""
+
+    kind: _ContainerKind
+    size: int = 0
+    awaiting_subcontainer: bool = False
+
+
+class _JSONEmitter:
+    """
+    Helps incrementally emit compliant JSON text.
+
+    Useful when the data to serialize is slowly streaming in and minimal
+    response time is desired.
+
+    Example:
+        >>> from girder_client._jsonemitter import *  # NOQA
+        >>> self = _JSONEmitter()
+        >>> self.start_dict()
+        >>> self.end_dict()
+        {}
+        >>> self = _JSONEmitter()
+        >>> self.start_dict()
+        >>> self.setitem('k1', 'v1')
+        >>> self.setitem('k2', 'v2')
+        >>> self.setitem('k3', 'v3')
+        >>> self.end_dict()
+    """
+
+    def __init__(self, stream: TextIO | None = None, checks: bool = True) -> None:
+        """
+        Args:
+            stream: stream to write to (defaults to stdout)
+            checks: if True checks that operations are legal
+        """
+        self._stack: list[_Context] = [_Context('root')]
+        self.stream: TextIO = sys.stdout if stream is None else stream
+        self.checks: bool = checks
+
+    def _current(self) -> _Context:
+        """Return the current container context."""
+        return self._stack[-1]
+
+    def _assert_can_start_container(self, context: _Context) -> None:
+        """Validate that a new dict/list value may start in ``context``."""
+        if context.kind == 'root':
+            if context.size >= 1:
+                raise AssertionError('Top level can only contain one container')
+        elif context.kind == 'dict':
+            if not context.awaiting_subcontainer:
+                raise AssertionError(
+                    'Expected start_subcontainer(key) before starting a '
+                    f'nested container; context={context!r}'
+                )
+        elif context.kind != 'list':
+            raise AssertionError(f'Unknown container context={context!r}')
+
+    def _assert_can_write_dict_item(self, context: _Context) -> None:
+        """Validate that a plain key/value item may be written to a dict."""
+        if context.kind != 'dict':
+            raise AssertionError(
+                f"Expected current context to be 'dict', but got context={context!r}"
+            )
+        if context.awaiting_subcontainer:
+            raise AssertionError(
+                'Expected a nested dict/list after start_subcontainer(key), '
+                f'but got a plain dict item; context={context!r}'
+            )
+
+    def _assert_can_write_list_item(self, context: _Context) -> None:
+        """Validate that a plain value may be appended to a list."""
+        if context.kind != 'list':
+            raise AssertionError(
+                f"Expected current context to be 'list', but got context={context!r}"
+            )
+
+    def _prepare_value(self, context: _Context) -> None:
+        """
+        Write any separator needed before emitting the next JSON value.
+
+        ``start_subcontainer`` writes a dict key before the corresponding
+        container exists. In that one case, the dict item has already been
+        counted and separated, so starting the child container consumes the
+        pending state without writing another separator.
+        """
+        if context.awaiting_subcontainer:
+            context.awaiting_subcontainer = False
+            return
+
+        if context.size > 0:
+            self.stream.write(',\n')
+        elif context.kind != 'root':
+            self.stream.write('\n')
+        context.size += 1
+
+    def _start_container(self, kind: _ContainerKind, opener: str) -> None:
+        """Start a new list or dict container."""
+        context = self._current()
+        if self.checks:
+            self._assert_can_start_container(context)
+
+        self._prepare_value(context)
+        self.stream.write(opener)
+        self._stack.append(_Context(kind))
+
+    def _end_container(self, expected_kind: _ContainerKind, closer: str) -> None:
+        """End the current list or dict container."""
+        if len(self._stack) == 1:
+            raise AssertionError('No open container to end')
+
+        context = self._current()
+        if self.checks:
+            if context.awaiting_subcontainer:
+                raise AssertionError(
+                    'Expected a nested dict/list after start_subcontainer(key), '
+                    f'but the {context.kind!r} context is ending; context={context!r}'
+                )
+            if context.kind != expected_kind:
+                raise AssertionError(
+                    f'Expected current context to be {expected_kind!r}, '
+                    f'but got context={context!r}'
+                )
+
+        self._stack.pop()
+        if context.size > 0:
+            self.stream.write('\n')
+        self.stream.write(closer)
+
+    def start_list(self) -> None:
+        """
+        Start a new list context. Must be in a list, or in a dict with a
+        prepared subcontainer.
+        """
+        self._start_container('list', '[')
+
+    def start_dict(self) -> None:
+        """
+        Start a new dictionary context. Must be in a list, or in a dict with a
+        prepared subcontainer.
+        """
+        self._start_container('dict', '{')
+
+    def end_list(self) -> None:
+        """End the current list context."""
+        self._end_container('list', ']')
+
+    def end_dict(self) -> None:
+        """End the current dictionary context."""
+        self._end_container('dict', '}')
+
+    def start_subcontainer(self, key: str) -> None:
+        """
+        Add a key to a dictionary whose value will be a new container.
+
+        Args:
+            key: the key that maps to the new subcontainer
+
+        Can only be called if you are inside a dict context.
+        The next call must start a new dict or list container.
+        """
+        context = self._current()
+        if self.checks:
+            self._assert_can_write_dict_item(context)
+
+        self._prepare_value(context)
+        self.stream.write(json.dumps(key))
+        self.stream.write(': ')
+        context.awaiting_subcontainer = True
+
+    def setitem(self, key: str, value: Any) -> None:
+        """
+        Add an item to a dict context.
+
+        Args:
+            key: a string key
+            value: any JSON-serializable object
+        """
+        context = self._current()
+        if self.checks:
+            self._assert_can_write_dict_item(context)
+
+        self._prepare_value(context)
+        self.stream.write(json.dumps(key))
+        self.stream.write(': ')
+        self.stream.write(json.dumps(value))
+
+    def append(self, item: Any) -> None:
+        """
+        Add an item to a list context.
+
+        Args:
+            item: any JSON-serializable object
+        """
+        context = self._current()
+        if self.checks:
+            self._assert_can_write_list_item(context)
+
+        self._prepare_value(context)
+        self.stream.write(json.dumps(item))

{girder_client-5.0.6.dev2 → girder_client-5.0.6.dev10}/girder_client/cli.py

@@ -346,6 +346,283 @@ def _upload(gc, parent_type, parent_id, local_folder,
         blacklist=blacklist.split(','), dryRun=dry_run, reference=reference)
 
 
+_short_help = 'List contents of a user, collection, folder, item, or file'
+_long_help = """
+PARENT_ID is the id of a Girder user, collection, folder, item, or file.
+The command first shows the requested resource so opaque ids are identifiable,
+then lists any immediate child resources: users and collections contain folders,
+folders contain folders and items, items contain files, and files have no
+children. In JSON output, the requested resource is emitted as this_record.
+
+Examples:
+
+    # List USER: jon.crall
+    girder-client --api-url https://data.kitware.com/api/v1 list 598a19658d777f7d33e9c18b
+
+    # List COLLECTION: VIAME
+    girder-client --api-url https://data.kitware.com/api/v1 list 58b747ec8d777f0aef5d0f6a
+
+    # List FOLDER: kwimage_demodata
+    girder-client --api-url https://data.kitware.com/api/v1 list 647cfb2ca71cc6eae69303a4
+
+    # List ITEM: the paraview.png logo
+    girder-client --api-url https://data.kitware.com/api/v1 list 647cfb97a71cc6eae69303b5
+
+    # List FILE: the paraview.png logo
+    girder-client --api-url https://data.kitware.com/api/v1 list 647cfb97a71cc6eae69303b6
+""".rstrip()
+
+
+@main.command('list', short_help=_short_help, help='%s\n\n%s' % (_short_help, _long_help))
+@click.option('--parent-type', default='auto', show_default=True,
+              help='type of Girder parent target',
+              type=click.Choice(['folder', 'collection', 'user', 'item', 'file', 'auto']))
+@click.argument('parent_id')
+@click.option('--limit', default=None, type=click.INT,
+              help='maximum number of records to list')
+@click.option('--offset', default=None, type=click.INT,
+              help='starting offset into list')
+@click.option('--json', 'as_json', default=False, is_flag=True, show_default=True,
+              help='output machine-readable JSON')
+@click.pass_obj
+def _list(gc, parent_type, parent_id, limit, offset, as_json):
+    if parent_type == 'auto':
+        parent_type = _list_lookup_parent_type(gc, parent_id)
+
+    this_record = _list_get_resource(gc, parent_type, parent_id)
+
+    if as_json:
+        from girder_client._jsonemitter import _JSONEmitter
+        emitter = _JSONEmitter()
+        emitter.start_dict()
+    else:
+        emitter = None
+
+    _list_record_info(gc, this_record, emitter)
+
+    if parent_type in {'collection', 'user'}:
+        # Collections and users can have folder children.
+        child_types = ['folder']
+    elif parent_type == 'folder':
+        # Folders can have folders and items as children.
+        child_types = ['folder', 'item']
+    elif parent_type == 'item':
+        # The requested item is already shown as this_record; list its files.
+        child_types = ['file']
+    elif parent_type == 'file':
+        # Files have no children.
+        child_types = []
+    else:
+        raise KeyError(parent_type)
+
+    if child_types:
+        _list_children_info(gc, parent_id, parent_type,
+                            child_types, limit, offset, emitter)
+
+    if emitter:
+        emitter.end_dict()
+
+
+def _list_lookup_parent_type(gc, parent_id):
+    """
+    Resolve the Girder resource type for the list command.
+
+    The shared _lookup_parent_type helper uses the resource path endpoint,
+    which can fail to identify users. Fall back to direct resource GETs, and
+    for users also try listing folders with parentType=user because some Girder
+    deployments allow traversing a user's public folders without allowing the
+    user record itself to be read anonymously.
+    """
+    lookup_errors = []
+    try:
+        parent_type = _lookup_parent_type(gc, parent_id)
+    except requests.HTTPError as exc_info:
+        lookup_errors.append('resource path lookup: %s' % _list_http_error_summary(exc_info))
+    else:
+        if parent_type is not None:
+            return parent_type
+        lookup_errors.append('resource path lookup: no match')
+
+    for candidate_type in ['folder', 'collection', 'item', 'file']:
+        try:
+            _list_get_resource(gc, candidate_type, parent_id)
+            return candidate_type
+        except requests.HTTPError as exc_info:
+            if exc_info.response.status_code in {400, 403, 404}:
+                lookup_errors.append('%s: %s' % (
+                    candidate_type, _list_http_error_summary(exc_info)))
+                continue
+            raise
+
+    user_status = _list_probe_user_resource(gc, parent_id)
+    if user_status is True:
+        return 'user'
+    lookup_errors.append('user: %s' % user_status)
+
+    raise click.ClickException(
+        'Could not determine Girder resource type for %s. Tried: %s' % (
+            parent_id, '; '.join(lookup_errors)))
+
+
+def _list_http_error_summary(exc_info):
+    """
+    Return a short description of a Girder HTTP lookup failure.
+    """
+    response = exc_info.response
+    status_code = getattr(response, 'status_code', None)
+    reason = getattr(response, 'reason', '')
+    if status_code is None:
+        return str(exc_info)
+    if reason:
+        return '%s %s' % (status_code, reason)
+    return str(status_code)
+
+
+def _list_probe_user_resource(gc, user_id):
+    """
+    Return True if user_id appears to identify a user resource.
+
+    A user record can be inaccessible while its public folders are still
+    listable, so direct GET /user/<id> is not the only useful probe.
+    """
+    try:
+        record = gc.get('user/%s' % user_id)
+    except requests.HTTPError as exc_info:
+        direct_status = _list_http_error_summary(exc_info)
+        if exc_info.response.status_code not in {400, 403, 404}:
+            raise
+    else:
+        if record:
+            return True
+        direct_status = 'empty response'
+
+    try:
+        records = gc.listFolder(user_id, parentFolderType='user', limit=1)
+        first_record = next(iter(records), None)
+    except requests.HTTPError as exc_info:
+        if exc_info.response.status_code not in {400, 403, 404}:
+            raise
+        return 'GET user failed with %s; folder probe failed with %s' % (
+            direct_status, _list_http_error_summary(exc_info))
+
+    if first_record is not None:
+        return True
+    return 'GET user failed with %s; folder probe returned no folders' % direct_status
+
+
+def _list_get_resource(gc, resource_type, resource_id):
+    """
+    Return a Girder record for a supported list resource type.
+
+    GirderClient.getResource handles collections, folders, items, and files.
+    User records are fetched through the user endpoint when possible. If the
+    user record is not readable, return a minimal user-shaped record so the CLI
+    can still show the requested opaque ID and list public folders below it.
+    """
+    if resource_type == 'user':
+        try:
+            record = gc.get('user/%s' % resource_id)
+        except requests.HTTPError as exc_info:
+            if exc_info.response.status_code in {400, 403, 404}:
+                return {
+                    '_id': resource_id,
+                    '_modelType': 'user',
+                }
+            raise
+        record.setdefault('_modelType', 'user')
+        return record
+    return gc.getResource(resource_type, resource_id)
+
+
+def _list_record_label(record):
+    """
+    Return a compact label for a Girder record.
+    """
+    return record.get('name') or record.get('login') or record.get('_id')
+
+
+def _list_record_info(gc, this_record, emitter):
+    """
+    Helper for :func:`_list` to print the requested record and its parents.
+    """
+    this_type = this_record.get('_modelType')
+    if this_type == 'folder':
+        prev_record = gc.getResource(this_record['parentCollection'], this_record['parentId'])
+        if emitter:
+            emitter.setitem('parent_record', prev_record)
+        else:
+            print('Parent {_modelType}: {_id} - {}'.format(
+                _list_record_label(prev_record), **prev_record))
+    elif this_type == 'item':
+        prev_record = gc.getResource('folder', this_record['folderId'])
+        if emitter:
+            emitter.setitem('parent_record', prev_record)
+        else:
+            print('Parent {_modelType}: {_id} - {}'.format(
+                _list_record_label(prev_record), **prev_record))
+    elif this_type == 'file':
+        item_record = gc.getResource('item', this_record['itemId'])
+        folder_record = gc.getResource('folder', item_record['folderId'])
+        if emitter:
+            emitter.setitem('item_record', item_record)
+            emitter.setitem('folder_record', folder_record)
+        else:
+            print('Parent folder: {_id} - {}'.format(
+                _list_record_label(folder_record), **folder_record))
+            print('Parent item: {_id} - {}'.format(
+                _list_record_label(item_record), **item_record))
+    elif this_type in {'collection', 'user'}:
+        # Collections and users do not have a single parent record to show here.
+        pass
+    else:
+        raise KeyError(this_type)
+
+    if emitter:
+        emitter.setitem('this_record', this_record)
+    else:
+        print('Listing {_modelType}: {_id} - {}'.format(
+            _list_record_label(this_record), **this_record))
+
+
+def _list_children_info(gc, parent_id, parent_type, child_types,
+                        limit, offset, emitter):
+    """
+    Helper for :func:`_list` to print nested records.
+    """
+    import itertools
+    for child_type in child_types:
+        if child_type == 'folder':
+            records = gc.listFolder(parent_id, limit=limit, offset=offset,
+                                    parentFolderType=parent_type)
+        elif child_type == 'item':
+            records = gc.listItem(parent_id, limit=limit, offset=offset)
+        elif child_type == 'file':
+            records = gc.listFile(parent_id, limit=limit, offset=offset)
+        else:
+            raise NotImplementedError
+
+        # Check if records has at least one element without losing it.
+        records_copy, records = itertools.tee(records)
+        first_records = list(itertools.islice(records_copy, 1))
+        if first_records:
+            if emitter:
+                emitter.start_subcontainer(f'{child_type}_children')
+                emitter.start_list()
+            else:
+                print('=== {} ==='.format(child_type))
+                print('{:<24} {:<6} {:<24}'.format('ID', 'TYPE', 'NAME'))
+
+        for record in records:
+            if emitter:
+                emitter.append(record)
+            else:
+                print('{_id:<24} {_modelType:<6} {}'.format(
+                    _list_record_label(record), **record))
+
+        if first_records and emitter:
+            emitter.end_list()
+
+
 if __name__ == '__main__':
     click.echo('Deprecation notice: Use "girder-client" to run the CLI.', err=True)
     main()

{girder_client-5.0.6.dev2 → girder_client-5.0.6.dev10}/girder_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: girder-client
-Version: 5.0.6.dev2
+Version: 5.0.6.dev10
 Summary: Python client for interacting with Girder servers
 Home-page: http://girder.readthedocs.org/en/latest/python-client.html
 Author: Kitware, Inc.

{girder_client-5.0.6.dev2 → girder_client-5.0.6.dev10}/girder_client.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.rst
 pyproject.toml
 setup.py
 girder_client/__init__.py
+girder_client/_jsonemitter.py
 girder_client/cli.py
 girder_client.egg-info/PKG-INFO
 girder_client.egg-info/SOURCES.txt