dump-things-pyclient 0.1.0__tar.gz

dump_things_pyclient-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: dump-things-pyclient
+Version: 0.1.0
+Summary: A client library and some CLI command for dump-things-services
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.5
+
+# Dump Things Python Client
+
+A simple client library for dump-things-service in Python
+
+
+## Tech Stack
+
+- Python >= 3.11
+
+- [uv](https://astral.sh/uv) for dependency management
+
+
+## Acknowledgements
+
+This work was funded, in part, by:
+
+- Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under grant TRR 379 (546006540, Q02 project)
+
+- MKW-NRW: Ministerium für Kultur und Wissenschaft des Landes Nordrhein-Westfalen under the Kooperationsplattformen 2022 program, grant number: KP22-106A

dump_things_pyclient-0.1.0/README.md

@@ -0,0 +1,19 @@
+# Dump Things Python Client
+
+A simple client library for dump-things-service in Python
+
+
+## Tech Stack
+
+- Python >= 3.11
+
+- [uv](https://astral.sh/uv) for dependency management
+
+
+## Acknowledgements
+
+This work was funded, in part, by:
+
+- Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under grant TRR 379 (546006540, Q02 project)
+
+- MKW-NRW: Ministerium für Kultur und Wissenschaft des Landes Nordrhein-Westfalen under the Kooperationsplattformen 2022 program, grant number: KP22-106A

dump_things_pyclient-0.1.0/dump_things_pyclient/__init__.py

@@ -0,0 +1,6 @@
+from typing import (
+    Any,
+    Union,
+)
+
+JSON = Union[dict[str, Any], list[Any], bool, str, int, float, None]

dump_things_pyclient-0.1.0/dump_things_pyclient/commands/auto_curate.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import re
+import sys
+
+from ..communicate import (
+    HTTPError,
+    curated_write_record,
+    incoming_delete_record,
+    incoming_read_labels,
+    incoming_read_records,
+)
+
+
+logger = logging.getLogger('auto-curate')
+
+token_name = 'DUMPTHINGS_TOKEN'
+
+stl_info = False
+
+description=f"""
+Automatically move records from the incoming areas of a
+collection to the curated area of the same collection, or to
+the curated area of another collection.
+
+The environment variable "{token_name}" must contain a token
+which used to authenticate the requests. The token must have
+curator-rights.
+"""
+
+
+def _main():
+    argument_parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    argument_parser.add_argument('service_url', metavar='SOURCE_SERVICE_URL')
+    argument_parser.add_argument('collection', metavar='SOURCE_COLLECTION')
+    argument_parser.add_argument(
+        '--destination-service-url',
+        default=None,
+        metavar='DEST_SERVICE_URL',
+        help='select a different dump-thing-service, i.e. not SOURCE_SERVICE_URL, as destination for auto-curated records',
+    )
+    argument_parser.add_argument(
+        '--destination-collection',
+        default=None,
+        metavar='DEST_COLLECTION',
+        help='select a different collection, i.e. not the SOURCE_COLLECTION of SOURCE_SERVICE_URL, as destination for auto-curated records',
+    ),
+    argument_parser.add_argument(
+        '--destination-token',
+        default=None,
+        metavar='DEST_TOKEN',
+        help='if provided, this token will be used for the destination service, otherwise ${CURATOR_TOKEN} will be used',
+    )
+    argument_parser.add_argument(
+        '-e', '--exclude',
+        action='append',
+        default=[],
+        help='exclude an inbox on the source collection (repeatable)',
+    )
+    argument_parser.add_argument(
+        '-l', '--list-labels',
+        action='store_true',
+        help='list the inbox labels of the given source collection, do not perform any curation',
+    )
+    argument_parser.add_argument(
+        '-r', '--list-records',
+        action='store_true',
+        help='list records in the inboxes of the given source collection, do not perform any curation',
+    )
+    argument_parser.add_argument(
+        '-p', '--pid',
+        action='append',
+        help='if provided, process only records that match the given PIDs. NOTE: matching does not involve CURIE-resolution!',
+    )
+    arguments = argument_parser.parse_args()
+
+    curator_token = os.environ.get(token_name)
+    if curator_token is None:
+        print(f'ERROR: environment variable "{token_name}" not set', file=sys.stderr, flush=True)
+        return 1
+
+    destination_url = arguments.destination_service_url or arguments.service_url
+    destination_collection = arguments.destination_collection or arguments.collection
+    destination_token = arguments.destination_token or curator_token
+
+    output = None
+
+    # If --list-labels and --list-records are provided, keep only the latter,
+    # because it includes listing of labels
+    if arguments.list_records:
+        if arguments.list_labels:
+            print('WARNING: `-l/--list-labels` and `-r/--list-records` defined, ignoring `-l/--list-labels`', file=sys.stderr, flush=True)
+            arguments.list_labels = False
+        output = {}
+    if arguments.list_labels:
+        output = []
+
+    for label in incoming_read_labels(
+                 service_url=arguments.service_url,
+                 collection=arguments.collection,
+                 token=curator_token):
+
+        if label in arguments.exclude:
+            logger.debug('ignoring excluded incoming label: %s', label)
+            continue
+
+        if arguments.list_labels:
+            output.append(label)
+            continue
+
+        if arguments.list_records:
+            output[label] = []
+
+        for record, _, _, _, _ in incoming_read_records(
+                                  service_url=arguments.service_url,
+                                  collection=arguments.collection,
+                                  label=label,
+                                  token=curator_token):
+
+            if arguments.pid:
+                if record['pid'] not in arguments.pid:
+                    logger.debug(
+                        'ignoring record with non-matching pid: %s',
+                        record['pid'])
+                    continue
+
+            if arguments.list_records:
+                output[label].append(record)
+                continue
+
+            # Get the class name from the `schema_type` attribute. This requires
+            # that the schema type is either stored in the record or that the
+            # store has a "Schema Type Layer", i.e., the store type is
+            # `record_dir+stl`, or `sqlite+stl`.
+            try:
+                class_name = re.search('([_A-Za-z0-9]*$)', record['schema_type']).group(0)
+            except IndexError:
+                global stl_info
+                if not stl_info:
+                    print(
+                        f"""Could not find `schema_type` attribute in record with
+                            pid {record['pid']}. Please ensure that `schema_type` is stored in
+                            the records or that the associated incoming area store has a backend
+                            with a "Schema Type Layer", i.e., "record_dir+stl" or
+                            "sqlite+stl".""",
+                        file=sys.stderr,
+                        flush=True)
+                    stl_info = True
+                print(
+                    f'WARNING: ignoring record with pid {record["pid"]}, `schema_type` attribute is missing.',
+                    file=sys.stderr,
+                    flush=True)
+                continue
+
+            # Store record in destination collection
+            curated_write_record(
+                service_url=destination_url,
+                collection=destination_collection,
+                class_name=class_name,
+                record=record,
+                token=destination_token)
+
+            # Delete record from incoming area
+            incoming_delete_record(
+                service_url=arguments.service_url,
+                collection=arguments.collection,
+                label=label,
+                pid=record['pid'],
+                token=curator_token,
+            )
+
+    if output is not None:
+        print(json.dumps(output, ensure_ascii=False))
+
+    return 0
+
+
+def main():
+    try:
+        return _main()
+    except HTTPError as e:
+        print(f'ERROR: {e}: {e.response.text}', file=sys.stderr, flush=True)
+    return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

dump_things_pyclient-0.1.0/dump_things_pyclient/commands/get_records.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from functools import partial
+
+from ..communicate import (
+    HTTPError,
+    collection_read_records,
+    collection_read_records_of_class,
+    collection_read_record_with_pid,
+    curated_read_records,
+    curated_read_records_of_class,
+    curated_read_record_with_pid,
+    incoming_read_labels,
+    incoming_read_records,
+    incoming_read_records_of_class,
+    incoming_read_record_with_pid,
+)
+
+
+token_name = 'DUMPTHINGS_TOKEN'
+
+description = f"""Get records from a collection on a dump-things-service
+
+This command lists records that are stored in a dump-things-service. By
+default all records that are readable with the given token, or the default
+token, will be displayed. The output format is JSONL (JSON lines), where
+every line contains a record or a record with paging information.  If `ttl`
+is chosen as format of the output records, the record content will be a string
+that contains a TTL-documents.
+
+The command supports to read from the curated area only, to read from incoming
+areas, or to read records with a given PID.
+
+Pagination information is returned for paginated results, when requested with
+`-P/--pagination`. All results are paginated except "get a record with a given PID"
+ and "get the list of incoming zone labels".
+
+If the environment variable "{token_name}" is set, its content will be used
+as token to authenticate against the dump-things-service.
+
+"""
+
+
+def _main():
+    argument_parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    argument_parser.add_argument('service_url')
+    argument_parser.add_argument('collection')
+    argument_parser.add_argument('-C', '--class', dest='class_name', help='only read records of this class, ignored if "--pid" is provided')
+    argument_parser.add_argument('-f', '--format', help='format of the output records ("json" or "ttl")')
+    argument_parser.add_argument('-p', '--pid', help='the pid of the record that should be read')
+    argument_parser.add_argument('-i', '--incoming', metavar='LABEL', help='read from incoming area with the given label in the collection, if LABEL is "-", return the labels')
+    argument_parser.add_argument('-c', '--curated', action='store_true', help='read from the curated area of the collection')
+    argument_parser.add_argument('-m', '--matching', help='return only records that have a matching value (use % as wildcard). Ignored if "--pid" is provided. (NOTE: not all endpoints and backends support matching.)')
+    argument_parser.add_argument('-s', '--page-size', type=int, help='set the page size (1 - 100) (default: 100), ignored if "--pid" is provided')
+    argument_parser.add_argument('-F', '--first-page', type=int, help='the first page to return (default: 1), ignored if "--pid" is provided')
+    argument_parser.add_argument('-l', '--last-page', type=int, default=None, help='the last page to return (default: None (return all pages), ignored if "--pid" is provided')
+    argument_parser.add_argument('--stats', action='store_true', help='show the number of records and pages and exit, ignored if "--pid" is provided')
+    argument_parser.add_argument('-P', '--pagination', action='store_true', help='show pagination information (each record from an paginated endpoint is returned as [<record>, <current page number>, <total number of pages>, <page size>, <total number of items>]')
+
+    arguments = argument_parser.parse_args()
+
+    token = os.environ.get(token_name)
+    if token is None:
+        print(f'WARNING: {token_name} not set', file=sys.stderr, flush=True)
+
+    if arguments.incoming and arguments.curated:
+        print(
+            'ERROR: -i/--incoming and -c/--curated are mutually exclusive',
+            file=sys.stderr,
+            flush=True)
+        return 1
+
+    kwargs = dict(
+        service_url=arguments.service_url,
+        collection=arguments.collection,
+        token=token,
+    )
+
+    if arguments.incoming == '-':
+        result = incoming_read_labels(**kwargs)
+        print('\n'.join(
+            map(
+                partial(json.dumps, ensure_ascii=False),
+                result)))
+        return 0
+
+    elif arguments.pid:
+        for argument_value, argument_name in (
+                (arguments.matching, '-m/--matching'),
+                (arguments.page_size, '-s/--page_size'),
+                (arguments.first_page, '-f/--first_page'),
+                (arguments.last_page, '-l/--last_page'),
+                (arguments.stats, '--stats'),
+                (arguments.class_name, '-c/--class'),
+        ):
+            if argument_value:
+                print(
+                    f'WARNING: {argument_name} ignored because "-p/--pid" is provided',
+                    file=sys.stderr,
+                    flush=True)
+
+        kwargs['pid'] = arguments.pid
+        if arguments.curated:
+            result = curated_read_record_with_pid(**kwargs)
+        elif arguments.incoming:
+            kwargs['label'] = arguments.incoming
+            result = incoming_read_record_with_pid(**kwargs)
+        else:
+            kwargs['format'] = arguments.format
+            result = collection_read_record_with_pid(**kwargs)
+        print(json.dumps(result, ensure_ascii=False))
+        return 0
+
+    elif arguments.class_name:
+        kwargs.update(dict(
+            class_name=arguments.class_name,
+            matching=arguments.matching,
+            page=arguments.first_page or 1,
+            size=arguments.page_size or 100,
+            last_page=arguments.last_page,
+        ))
+        if arguments.curated:
+            result = curated_read_records_of_class(**kwargs)
+        elif arguments.incoming:
+            kwargs['label'] = arguments.incoming
+            result = incoming_read_records_of_class(**kwargs)
+        else:
+            kwargs['format'] = arguments.format
+            result = collection_read_records_of_class(**kwargs)
+    else:
+        kwargs.update(dict(
+            matching=arguments.matching,
+            page=arguments.first_page or 1,
+            size=arguments.page_size or 100,
+            last_page=arguments.last_page,
+        ))
+        if arguments.curated:
+            result = curated_read_records(**kwargs)
+        elif arguments.incoming:
+            kwargs['label'] = arguments.incoming
+            result = incoming_read_records(**kwargs)
+        else:
+            kwargs['format'] = arguments.format
+            result = collection_read_records(**kwargs)
+
+    if arguments.pagination:
+        for record in result:
+            print(json.dumps(record, ensure_ascii=False))
+    else:
+        for record in result:
+            print(json.dumps(record[0], ensure_ascii=False))
+    return 0
+
+
+def main():
+    try:
+        return _main()
+    except HTTPError as e:
+        print(f'ERROR: {e}: {e.response.text}', file=sys.stderr, flush=True)
+    return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

dump_things_pyclient-0.1.0/dump_things_pyclient/commands/read_pages.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from ..communicate import (
+    HTTPError,
+    get_paginated,
+)
+
+
+token_name = 'DUMPTHINGS_TOKEN'
+
+description = f"""Read paginated endpoint
+
+This command lists all records that are available via paginated endpoints from
+a dump-things-service, e.g., from:
+  
+  https://<service-location>/<collection>/records/p/
+
+If the environment variable "{token_name}" is set, its content will be used
+as token to authenticate against the dump-things-service.
+
+"""
+
+
+def _main():
+    argument_parser = argparse.ArgumentParser(
+        description=description,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    argument_parser.add_argument('url', help='url of the paginated endpoint of the dump-things-service')
+    argument_parser.add_argument('-s', '--page-size', type=int, default=100, help='set the page size (1 - 100) (default: 100)')
+    argument_parser.add_argument('-F', '--first-page', type=int, default=1, help='the first page to return (default: 1)')
+    argument_parser.add_argument('-l', '--last-page', type=int, default=None, help='the last page to return (default: None (return all pages)')
+    argument_parser.add_argument('--stats', action='store_true', help='show information about  the number of records and pages and exit, the format is  is returned as [<total number of pages>, <page size>, <total number of items>]')
+    argument_parser.add_argument('-f', '--format', help='format of the output records ("json" or "ttl"). (NOTE: not all endpoints support the format parameter.)')
+    argument_parser.add_argument('-m', '--matching', help='return only records that have a matching value (use % as wildcard). (NOTE: not all endpoints and backends support matching.)')
+    argument_parser.add_argument('-P', '--pagination', action='store_true', help='show pagination information (each record from an paginated endpoint is returned as [<record>, <current page number>, <total number of pages>, <page size>, <total number of items>]')
+
+    arguments = argument_parser.parse_args()
+
+    token = os.environ.get(token_name)
+    if token is None:
+        print(f'WARNING: {token_name} not set', file=sys.stderr, flush=True)
+
+    result = get_paginated(
+        url=arguments.url,
+        first_page=arguments.first_page,
+        page_size=arguments.page_size,
+        last_page=arguments.last_page,
+        parameters={
+            'format': arguments.format,
+            **({'matching': arguments.matching}
+               if arguments.matching is not None
+               else {}
+            ),
+        }
+    )
+
+    if arguments.stats:
+        record = next(result)
+        print(json.dumps(record[2:], ensure_ascii=False))
+        return 0
+
+    if arguments.pagination:
+        for record in result:
+            print(json.dumps(record, ensure_ascii=False))
+    else:
+        for record in result:
+            print(json.dumps(record[0], ensure_ascii=False))
+    return 0
+
+
+def main():
+    try:
+        return _main()
+    except HTTPError as e:
+        print(f'ERROR: {e}: {e.response.text}', file=sys.stderr, flush=True)
+    return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

dump_things_pyclient-0.1.0/dump_things_pyclient/communicate.py

@@ -0,0 +1,719 @@
+from __future__ import annotations
+
+import logging
+from itertools import count
+from typing import (
+    Callable,
+    Generator,
+)
+
+import requests
+from requests.exceptions import HTTPError
+
+from . import JSON
+
+
+__all__ = [
+    'HTTPError',
+    'JSON',
+    'get_paginated',
+    'get',
+    'collection_delete_record',
+    'collection_read_records',
+    'collection_read_records_of_class',
+    'collection_read_record_with_pid',
+    'collection_validate_record',
+    'collection_write_record',
+    'curated_delete_record',
+    'curated_read_records',
+    'curated_read_records_of_class',
+    'curated_read_record_with_pid',
+    'curated_write_record',
+    'incoming_delete_record',
+    'incoming_read_labels',
+    'incoming_read_records',
+    'incoming_read_records_of_class',
+    'incoming_read_record_with_pid',
+    'incoming_write_record',
+]
+
+
+logger = logging.getLogger('dump_things_pyclient')
+
+
+def get_paginated(url: str,
+                  token: str | None = None,
+                  first_page: int = 1,
+                  page_size: int = 100,
+                  last_page: int | None = None,
+                  parameters: dict[str, str] | None = None,
+                  ) -> Generator[tuple[JSON, int, int, int, int], None, None]:
+    """Read all records from a paginated endpoint
+
+    :param url: URL of the paginated endpoint, e.g., `https://.../records/p/`
+    :param token: [optional] if str: token to authenticate against the endpoint,
+           if None: no token will be sent to the endpoint
+    :param first_page: [optional] first page to return (default: 1)
+    :param page_size: [optional] size of pages (default: 100)
+    :param last_page: [optional] last page to return (default: None (return all pages))
+    :param parameters: [optional] parameters to pass to the endpoint, the
+           parameter `page` is set automatically in this function
+
+    :return: a Generator yielding tuples containing the current record, the
+             current page number, the total number of pages, the size of the pages,
+             and total number of records
+    """
+    if last_page and last_page < first_page:
+        logger.warning('last_page (%d) < first_page (%d)', last_page, first_page)
+        return
+
+    for page in count(start=first_page):
+        result = _get_page(url, token, first_page=page, page_size=page_size, parameters=parameters)
+        total_pages, page_size, total_items = result['pages'], result['size'], result['total']
+        if total_pages == 0:
+            return
+        if last_page is None:
+            last_page = total_pages
+
+        yield from (
+            (record, page, total_pages, page_size, total_items)
+            for record in result['items'])
+
+        if page == min(last_page, total_pages):
+            return
+
+
+def get(url: str,
+        token: str | None = None,
+        parameters: dict[str, str] | None = None,
+        ) -> JSON:
+    """Read JSON object from a non-paginated endpoint
+
+    :param url: URL of the endpoint, e.g., `https://.../records/`.
+    :param token: [optional] if str: token to authenticate against the endpoint,
+           if None: no token will be sent to the endpoint
+    :param parameters: [optional] parameters to pass to the endpoint
+
+    :return: JSON object
+    """
+    return _get_from_url(url, token, parameters)
+
+
+def collection_read_record_with_pid(service_url: str,
+                                    collection: str,
+                                    pid: str,
+                                    format: str = 'json',
+                                    token: str | None = None,
+                                    ) -> dict | None:
+    """Read record with the given pid from the collection on the service
+
+    Records are read from the curated area of the collection and from the
+    incoming area of the user identified by token, if a token is given.
+    Records from incoming areas take preference.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param pid: the PID of the record that should be retrieved
+    :param format: the format in which the result record should be returned,
+           either `json` or `ttl`
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+
+    :return: The record, if it exists, None otherwise.
+    """
+    return get(
+            url=_build_url(service_url, collection, 'record'),
+            token=token,
+            parameters={'pid': pid, 'format': format})
+
+
+def collection_read_records(service_url: str,
+                            collection: str,
+                            matching: str | None = None,
+                            format: str = 'json',
+                            token: str | None = None,
+                            page: int = 1,
+                            size: int = 100,
+                            last_page: int | None = None,
+                            ) -> Generator[tuple[dict, int, int, int, int], None, None]:
+    """Read records from the collection on the service
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param matching: [optional] return only records that have a matching value
+           (string comparison with `%` as wildcard)
+    :param format: the format in which the result records should be returned,
+           either `json` or `ttl` (default: `json`)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint.
+    :param page: int: the first page that should be returned (default: 1)
+    :param size: int: the number of records in an individual pages (default: 100)
+    :param last_page: int | None: if int, the last page that should be returned
+           if None, all pages following `page` will be returned
+
+    :return: A generator yielding tuples containing: the current record, the
+             current page number, the total number of pages, the size of the
+             pages, the total number of records
+    """
+    return get_paginated(
+        url=_build_url(service_url, collection, 'records/p/'),
+        token=token,
+        first_page=page,
+        page_size=size,
+        last_page=last_page,
+        parameters= {
+            'format': format,
+            **({'matching': matching} if matching else {})})
+
+
+def collection_read_records_of_class(
+        service_url: str,
+        collection: str,
+        class_name: str,
+        matching: str | None = None,
+        format: str = 'json',
+        token: str | None = None,
+        page: int = 1,
+        size: int = 100,
+        last_page: int | None = None,
+) -> Generator[tuple[dict, int, int, int, int], None, None]:
+    """Read records of the specified class from the collection on the service
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param class_name: the name of the class whose instances should be returned
+    :param matching: [optional] return only records that have a matching value
+           (string comparison with `%` as wildcard)
+    :param format: the format in which the result records should be returned,
+           either `json` or `ttl` (default: `json`)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint.
+    :param page: int: the first page that should be returned (default: 1)
+    :param size: int: the number of records in an individual pages (default: 100)
+    :param last_page: int | None: if int, the last page that should be returned
+           if None, all pages following `page` will be returned
+
+    :return: A generator yielding tuples containing: the current record, the
+             current page number, the total number of pages, the size of the
+             pages, the total number of records
+    """
+    return get_paginated(
+        url=_build_url(service_url, collection, f'records/p/{class_name}'),
+        token=token,
+        first_page=page,
+        page_size=size,
+        last_page=last_page,
+        parameters= {
+            'format': format,
+            **({'matching': matching} if matching else {})})
+
+
+def collection_write_record(
+        service_url: str,
+        collection: str,
+        class_name: str,
+        record: dict | str,
+        format: str = 'json',
+        token: str | None = None,
+) -> list[JSON]:
+    """Write a record of the specified class to an inbox in the collection on the service
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param class_name: the class of the record given in `record`
+    :param record: dict | str: the record that should be written
+    :param format: the format of `record`, either `json` or `ttl`
+           (default: `json`)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           The token must have write access to incoming area in the collection
+
+    :return list[JSON]: a list of records that was written. There might be more
+            than one record due to inlined-relations extraction. The individual
+            records might have annotations added
+    """
+    return _post_to_url(
+        url=_build_url(service_url, collection, f'record/{class_name}'),
+        token=token,
+        json=record,
+        params={'format': format})
+
+
+def collection_validate_record(
+        service_url: str,
+        collection: str,
+        class_name: str,
+        record: dict | str,
+        format: str = 'json',
+        token: str | None = None,
+) -> list[JSON]:
+    """Validate a record of the specified class in the collection on the service
+
+    Validation involves conversion of the record from json to ttl, or from
+    ttl to json.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param class_name: the class of the record given in `record`
+    :param record: dict | str: the record that should be validated
+    :param format: the format of `record`, either `json` or `ttl`
+           (default: `json`)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           The token must have write access to incoming area in the collection
+
+    :return: True
+    """
+    service_url = f'{service_url[:-1]}' if service_url.endswith('/') else service_url
+    return _post_to_url(
+        url=_build_url(service_url, collection, f'validate/{class_name}'),
+        token=token,
+        json=record,
+        params={'format': format})
+
+
+def collection_delete_record(
+        service_url: str,
+        collection: str,
+        pid: str,
+        token: str | None = None,
+) -> bool:
+    """Delete the record with the given pid from the collection on the service
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param pid: the PID of the record that should be deleted
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+
+    :return: True if the record was deleted, False otherwise
+    """
+    return _delete_url(
+        url=_build_url(service_url, collection, 'record'),
+        token=token,
+        params={'pid': pid})
+
+
+def curated_read_record_with_pid(service_url: str,
+                                 collection: str,
+                                 pid: str,
+                                 token: str | None = None,
+                                 ) -> dict | None:
+    """Read record with the given pid from curated area of the collection on the service
+
+    The record will be returned as it is stored in the backend. That means
+    there is no "Schema-Type-Layer" involved.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param pid: the PID of the record that should be retrieved
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint. A
+           token must have curator-rights
+
+    :return: The record, if it exists, None otherwise
+    """
+    return get(
+        url=_build_url(service_url, collection, 'curated/record'),
+        token=token,
+        parameters={'pid': pid})
+
+
+def curated_read_records(service_url: str,
+                         collection: str,
+                         matching: str | None = None,
+                         token: str | None = None,
+                         page: int = 1,
+                         size: int = 100,
+                         last_page: int | None = None,
+                         ) -> Generator[tuple[dict, int, int, int, int], None, None]:
+    """Read records from the curated area the collection on the service
+
+    Records will be returned as they are stored in the backend. That means
+    there is no "Schema-Type-Layer" involved.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param matching: [optional] return only records that have a matching value
+           (string comparison with `%` as wildcard)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint. A
+           token must have curator-rights
+    :param page: int: the first page that should be returned (default: 1)
+    :param size: int: the number of records in an individual pages (default: 100)
+    :param last_page: int | None: if int, the last page that should be returned
+           if None, all pages following `page` will be returned
+
+    :return: A generator yielding tuples containing: the current record, the
+             current page number, the total number of pages, the size of the
+             pages, the total number of records
+    """
+    return get_paginated(
+        url=_build_url(service_url, collection, 'curated/records/p/'),
+        token=token,
+        first_page=page,
+        page_size=size,
+        last_page=last_page,
+        parameters={'matching': matching} if matching else {})
+
+
+def curated_read_records_of_class(
+        service_url: str,
+        collection: str,
+        class_name: str,
+        matching: str | None = None,
+        token: str | None = None,
+        page: int = 1,
+        size: int = 100,
+        last_page: int | None = None,
+) -> Generator[tuple[dict, int, int, int, int], None, None]:
+    """Read records of class `class_name` from the curated area the collection on the service
+
+    Records will be returned as they are stored in the backend. That means
+    there is no "Schema-Type-Layer" involved.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param class_name: the name of the class whose instances should be returned
+    :param matching: [optional] return only records that have a matching value
+           (string comparison with `%` as wildcard)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint. A
+           token must have curator-rights for the collection
+    :param page: int: the first page that should be returned (default: 1)
+    :param size: int: the number of records in an individual pages (default: 100)
+    :param last_page: int | None: if int, the last page that should be returned
+           if None, all pages following `page` will be returned
+
+    :return: A generator yielding tuples containing: the current record, the
+             current page number, the total number of pages, the size of the
+             pages, the total number of records
+    """
+    return get_paginated(
+        url=_build_url(service_url, collection, f'curated/records/p/{class_name}'),
+        token=token,
+        first_page=page,
+        page_size=size,
+        last_page=last_page,
+        parameters={'matching': matching} if matching else {})
+
+
+def curated_write_record(
+        service_url: str,
+        collection: str,
+        class_name: str,
+        record: dict,
+        token: str | None = None,
+) -> list[JSON]:
+    """Write a record of the specified class to the curated area of the collection on the service
+
+    Records will be written without modification, i.e. there is no
+    "Schema-Type-Layer", there is no extraction of inlined records, and there
+    is no annotation-adding.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param class_name: the class of the record given in `record`
+    :param record: dict: the record that should be written
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           A given token must have curator-rights for the collection
+
+    :return list[JSON]: a list containing the record that was written
+    """
+    return _post_to_url(
+        url=_build_url(service_url, collection, f'curated/record/{class_name}'),
+        token=token,
+        json=record)
+
+
+def curated_delete_record(
+        service_url: str,
+        collection: str,
+        pid: str,
+        token: str | None = None,
+) -> bool:
+    """Delete the record with the given pid from the curated area of the collection on the service
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param pid: the PID of the record that should be deleted
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           A given token must have curator-rights for the collection
+    :return: True if the record was deleted, False otherwise
+    """
+    return _delete_url(
+        url=_build_url(service_url, collection, 'curated/record'),
+        token=token,
+        params={'pid': pid})
+
+
+def incoming_read_labels(service_url: str,
+                         collection: str,
+                         token: str | None = None,
+                         ) -> Generator[str, None, None]:
+    """Read all incoming labels for the collection on the service.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           A given token must have curator-rights for the collection
+
+    :return: list[str]: a list of incoming area labels
+    """
+    yield from _get_from_url(
+        url=_build_url(service_url, collection,'incoming/'),
+        token=token)
+
+
+def incoming_read_record_with_pid(service_url: str,
+                                  collection: str,
+                                  label: str,
+                                  pid: str,
+                                  token: str | None = None,
+                                  ) -> dict | None:
+    """Read record with the given pid from the specified incoming area of the collection on the service
+
+    The record will be returned as it is stored in the backend. That means
+    there is no "Schema-Type-Layer" involved.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param label: the label of the incoming area in the collection
+    :param pid: the PID of the record that should be retrieved
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint. A
+           token must have curator-rights
+
+    :return: The record, if it exists, None otherwise
+    """
+    return get(
+        url=_build_incoming_url(service_url, collection, label, 'record'),
+        token=token,
+        parameters={'pid': pid})
+
+
+def incoming_read_records(service_url: str,
+                          collection: str,
+                          label: str,
+                          matching: str | None = None,
+                          token: str | None = None,
+                          page: int = 1,
+                          size: int = 100,
+                          last_page: int | None = None,
+                          ) -> Generator[tuple[dict, int, int, int, int], None, None]:
+    """Read records from the specified incoming area the collection on the service
+
+    Records will be returned as they are stored in the backend. That means
+    there is no "Schema-Type-Layer" involved.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param label: the label of the incoming area in the collection
+    :param matching: [optional] return only records that have a matching value
+           (string comparison with `%` as wildcard)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint. A
+           token must have curator-rights for the collection
+    :param page: int: the first page that should be returned (default: 1)
+    :param size: int: the number of records in an individual pages (default: 100)
+    :param last_page: int | None: if int, the last page that should be returned
+           if None, all pages following `page` will be returned
+
+    :return: A generator yielding tuples containing: the current record, the
+             current page number, the total number of pages, the size of the
+             pages, the total number of records
+    """
+    return get_paginated(
+        url=_build_incoming_url(service_url, collection, label,'records/p/'),
+        token=token,
+        first_page=page,
+        page_size=size,
+        last_page=last_page,
+        parameters={'matching': matching} if matching else {})
+
+
+def incoming_read_records_of_class(
+        service_url: str,
+        collection: str,
+        label: str,
+        class_name: str,
+        matching: str | None = None,
+        token: str | None = None,
+        page: int = 1,
+        size: int = 100,
+        last_page: int | None = None,
+) -> Generator[tuple[dict, int, int, int, int], None, None]:
+    """Read records of the specified class from the specified incoming area the collection on the service
+
+    Records will be returned as they are stored in the backend. That means
+    there is no "Schema-Type-Layer" involved.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param label: the label of the incoming area in the collection
+    :param class_name: the name of the class whose instances should be returned
+    :param matching: [optional] return only records that have a matching value
+           (string comparison with `%` as wildcard)
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint. A
+           token must have curator-rights for the collection
+    :param page: int: the first page that should be returned (default: 1)
+    :param size: int: the number of records in an individual pages (default: 100)
+    :param last_page: int | None: if int, the last page that should be returned
+           if None, all pages following `page` will be returned
+
+    :return: A generator yielding tuples containing: the current record, the
+             current page number, the total number of pages, the size of the
+             pages, the total number of records
+    """
+    return get_paginated(
+        url=_build_incoming_url(service_url, collection, label,f'records/p/{class_name}'),
+        token=token,
+        first_page=page,
+        page_size=size,
+        last_page=last_page,
+        parameters={'matching': matching} if matching else {})
+
+
+def incoming_write_record(
+        service_url: str,
+        collection: str,
+        label: str,
+        class_name: str,
+        record: dict,
+        token: str | None = None,
+) -> list[JSON]:
+    """Write a record of the specified class to the specified incoming area of the collection on the service
+
+    Records will be written without modification, i.e. there is no
+    "Schema-Type-Layer", there is no extraction of inlined records, and there
+    is no annotation-adding.
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param label: the label of the incoming area in the collection
+    :param class_name: the class of the record given in `record`
+    :param record: dict: the record that should be written
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           A given token must have curator-rights for the collection
+
+    :return list[JSON]: a list containing the record that was written
+    """
+    return _post_to_url(
+        url=_build_incoming_url(service_url, collection, label, f'record/{class_name}'),
+        token=token,
+        json=record)
+
+
+def incoming_delete_record(
+        service_url: str,
+        collection: str,
+        label: str,
+        pid: str,
+        token: str | None = None,
+) -> bool:
+    """Delete the record with the given pid from the specified incoming area of the collection on the service
+
+    :param service_url: the base URL of the service, i.e., the URL up to
+           `/<collection>/...` or `/server`
+    :param collection: the name of the collection
+    :param label: the label of the incoming area in the collection
+    :param pid: the PID of the record that should be deleted
+    :param token: [optional] if set, a token to authenticate against
+           the endpoint, if None: no token will be sent to the endpoint
+           A given token must have curator-rights for the collection
+
+    :return: True if the record was deleted, False otherwise
+    """
+    return _delete_url(
+        url=_build_incoming_url(service_url, collection, label,'record'),
+        token=token,
+        params={'pid': pid})
+
+
+def _get_from_url(url: str,
+                  token: str | None,
+                  params: dict[str, str] | None = None,
+                  ) -> JSON:
+    return _do_request(requests.get, url, token, params=params)
+
+
+def _post_to_url(url: str,
+                 token: str | None,
+                 json: JSON,
+                 params: dict[str, str] | None = None,
+                 ) -> JSON:
+    return _do_request(requests.post, url, token, params, json=json)
+
+
+def _delete_url(url: str,
+                token: str | None,
+                params: dict[str, str] | None = None,
+                ) -> JSON:
+    return _do_request(requests.delete, url, token, params=params)
+
+
+def _do_request(method: Callable,
+                url: str,
+                token: str | object | None,
+                params: dict[str, str] | None,
+                **kwargs,
+                ) -> JSON:
+    headers = {'x-dumpthings-token': token} if token is not None else {}
+    response = method(url, headers=headers, params=params or {}, **kwargs)
+    response.raise_for_status()
+    if response.headers.get('content-type', '').strip().startswith('text/turtle'):
+        return response.text
+    return response.json()
+
+
+def _build_url(
+        service_url: str,
+        collection: str,
+        tail: str,
+) -> str:
+    service_url = f'{service_url[:-1]}' if service_url.endswith('/') else service_url
+    collection = f'{collection[:-1]}' if collection.endswith('/') else collection
+    return f'{service_url}/{collection}/{tail}'
+
+
+def _build_incoming_url(
+        service_url: str,
+        collection: str,
+        label: str,
+        tail: str,
+) -> str:
+    label = f'{label[:-1]}' if label.endswith('/') else label
+    return _build_url(service_url, collection, f'incoming/{label}/{tail}')
+
+
+def _get_page(url_base: str,
+              token: str | None = None,
+              first_page: int = 1,
+              page_size: int = 100,
+              parameters: dict | None = None,
+              ) -> JSON:
+    parameters = parameters or {}
+    parameters['page'] = first_page
+    parameters['size'] = page_size
+    return _get_from_url(url_base, token, parameters)

dump_things_pyclient-0.1.0/dump_things_pyclient.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: dump-things-pyclient
+Version: 0.1.0
+Summary: A client library and some CLI command for dump-things-services
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.5
+
+# Dump Things Python Client
+
+A simple client library for dump-things-service in Python
+
+
+## Tech Stack
+
+- Python >= 3.11
+
+- [uv](https://astral.sh/uv) for dependency management
+
+
+## Acknowledgements
+
+This work was funded, in part, by:
+
+- Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under grant TRR 379 (546006540, Q02 project)
+
+- MKW-NRW: Ministerium für Kultur und Wissenschaft des Landes Nordrhein-Westfalen under the Kooperationsplattformen 2022 program, grant number: KP22-106A

dump_things_pyclient-0.1.0/dump_things_pyclient.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+dump_things_pyclient/__init__.py
+dump_things_pyclient/communicate.py
+dump_things_pyclient.egg-info/PKG-INFO
+dump_things_pyclient.egg-info/SOURCES.txt
+dump_things_pyclient.egg-info/dependency_links.txt
+dump_things_pyclient.egg-info/entry_points.txt
+dump_things_pyclient.egg-info/requires.txt
+dump_things_pyclient.egg-info/top_level.txt
+dump_things_pyclient/commands/__init__.py
+dump_things_pyclient/commands/auto_curate.py
+dump_things_pyclient/commands/get_records.py
+dump_things_pyclient/commands/read_pages.py

dump_things_pyclient-0.1.0/dump_things_pyclient.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

dump_things_pyclient-0.1.0/dump_things_pyclient.egg-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+auto-curate = dump_things_pyclient.commands.auto_curate:main
+get-records = dump_things_pyclient.commands.get_records:main
+read-pages = dump_things_pyclient.commands.read_pages:main

dump_things_pyclient-0.1.0/dump_things_pyclient.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.32.5

dump_things_pyclient-0.1.0/dump_things_pyclient.egg-info/top_level.txt

@@ -0,0 +1 @@
+dump_things_pyclient

dump_things_pyclient-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "dump-things-pyclient"
+version = "0.1.0"
+description = "A client library and some CLI command for dump-things-services"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.32.5",
+]
+
+[dependency-groups]
+tests = [
+    "pytest>=9.0.1",
+]
+
+[project.scripts]
+auto-curate = "dump_things_pyclient.commands.auto_curate:main"
+read-pages = "dump_things_pyclient.commands.read_pages:main"
+get-records = "dump_things_pyclient.commands.get_records:main"

dump_things_pyclient-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+