sidex 1.5.1__py3-none-any.whl

sidex/__init__.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+''' Simple Data Exchange Server
+
+This module provides a minimal framework to launch a file server
+running on the middleware `Flask`. You are allowed to fetch, put,
+and delete files over HTTP.
+
+You can launch a server on the command line as follows:
+
+    python -m sidex.server --host localhost --port 8000 TARGET_DIR
+
+A file in the TARGET_DIR can be fetched by `wget`:
+
+    wget --post-data="method=get" http://localhost:8000/FILENAME
+
+or by using `sidex.client`:
+
+    python -m sidex.client http://localhost:8080/FILENAME
+
+The `POST` method is required since the `method` data is mandatory.
+The `get` method can be protected by setting a token.
+
+The `put` and `delete` methods are disabled by default. They can be
+enabled by setting tokens. Note that the token is just a passphrase
+and not ciphered at all. The transaction is never protected. Do not
+use the SIDEX in case that the network is untrastrul.
+
+The SIDEX provides a way to customize the functions. The default
+behaviors of any methods can be overridden.
+'''
+
+from .setup import setup
+from .request import request
+
+__version__ = '1.5.1'
+
+__all__ = [
+    '__version__',
+    'setup',
+    'request',
+]

sidex/client.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+''' A command-line SIDEX client.
+
+This file provides a command-line SIDEX client.
+A detailed usage is available by typing the following command:
+
+    python -m sidex.client -h
+'''
+
+import os, sys, re, requests
+
+
+if __name__ == '__main__':
+    from argparse import ArgumentParser as ap
+    parser = ap(prog='client', description='SIDEX minimal client')
+    parser.add_argument(
+        'filename', type=str, nargs='?',
+        help='filename to be uploaded (only requred in put mode)')
+    parser.add_argument(
+        'target', type=str,
+        help='address to SIDEX server')
+    parser.add_argument(
+        '-d', '--delete', action='store_true',
+        help='delete file')
+    parser.add_argument(
+        '-p', '--ping', action='store_true',
+        help='send ping message')
+    parser.add_argument(
+        '--token', metavar='token', type=str,
+        help='set token')
+
+    args = parser.parse_args()
+    # Leading "http://" can be omitted.
+    if not re.match('^https?://', args.target):
+        args.target = 'http://' + args.target
+    eprint = lambda s: print('error: '+s, file=sys.stderr)
+
+    if args.delete is True and args.filename is not None:
+        eprint('option conflicted.')
+        exit(1)
+
+    method = 'get'
+    files = None
+    filename = os.path.basename(args.target)
+
+    if args.ping is True:
+        method = 'ping'
+    if args.delete is True:
+        method = 'delete'
+    if args.filename is not None:
+        method = 'put'
+        with open(args.filename, 'rb') as f:
+            files = {'payload': f.read()}
+
+    if method == 'get' and os.path.exists(filename):
+        eprint('file "{}" already exists.'.format(filename))
+        exit(1)
+
+    try:
+        data = {'method': method, 'token': args.token}
+        req = requests.post(args.target, data=data, files=files)
+        if req.ok is False:
+            eprint(req.text.strip())
+            req.raise_for_status()
+
+        if method == 'get':
+            with open(filename, 'wb') as f:
+                f.write(req.content)
+        elif method == 'ping':
+            pass
+        else:
+            print(req.text.strip())
+    except Exception as e:
+        eprint(str(e))
+        exit(1)

sidex/dump.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+''' A command-line SIDEX client for dump.
+
+This file provides a command-line SIDEX client.
+A detailed usage is available by typing the following command:
+
+    python -m sidex.dump -h
+'''
+
+import os, sys, re, requests
+import io, gzip, bz2, lzma, tarfile
+
+
+if __name__ == '__main__':
+    from argparse import ArgumentParser as ap
+    parser = ap(prog='dump', description='SIDEX dump client')
+    parser.add_argument('target', type=str,
+        help='address to SIDEX server')
+    parser.add_argument('filename', type=str, nargs='+',
+        help='requested filename')
+    parser.add_argument(
+        '-f', '--overwrite', dest='overwrite', action='store_true',
+        help='overwrite files even if exists')
+    parser.add_argument(
+        '--tar', dest='tarball', type=str, action='store',
+        help='grab files as a tarball archive')
+    parser.add_argument(
+        '--token', dest='token', metavar='token', type=str,
+        help='set token')
+
+    args = parser.parse_args()
+    # Leading "http://" can be omitted.
+    if not re.match('^https?://', args.target):
+        args.target = 'http://' + args.target
+    eprint = lambda s: print('error: '+s, file=sys.stderr)
+
+    method = 'dump'
+
+    if not args.overwrite:
+        for f in args.filename:
+            if os.path.exists(f):
+                eprint('file "{}" already exists.'.format(f))
+                exit(1)
+
+    try:
+        data = {
+            'method': 'dump',
+            'token': args.token,
+            'filename': args.filename,
+        }
+        with requests.post(args.target, data=data, stream=True) as req:
+            if req.ok is False:
+                eprint(req.text.strip())
+                req.raise_for_status()
+
+            if args.tarball:
+                dummy, ext = os.path.splitext(args.tarball)
+                print(ext)
+                if ext == '.gz':
+                    with gzip.open(args.tarball, 'wb') as arv:
+                        for chunk in req.iter_content(65535): arv.write(chunk)
+                elif ext == '.bz2':
+                    with bz2.open(args.tarball, 'wb') as arv:
+                        for chunk in req.iter_content(65535): arv.write(chunk)
+                elif ext == '.xz':
+                    with lzma.open(args.tarball, 'wb') as arv:
+                        for chunk in req.iter_content(65535): arv.write(chunk)
+                else:
+                    with open(args.tarball, 'wb') as arv:
+                        for chunk in req.iter_content(65535): arv.write(chunk)
+            else:
+                buf = io.BytesIO(req.content)
+                with tarfile.open(fileobj=buf, mode='r:') as arv:
+                    arv.extractall()
+    except Exception as e:
+        eprint(str(e))
+        exit(1)

sidex/request.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+''' A function for a quick access to a sidex server.
+
+This module provides a helper function `sidex_request` to make
+a query to a sidex server.
+'''
+import os, requests
+
+
+def request(url, method, filename=None, token=None):
+    ''' Make a request to a sidex server.
+
+    Arguments:
+        url (str):
+            The url, which defines a query to a sidex server.
+        method (str):
+            The name of the requested method. The available methods
+            are `get`, `put`, and `delete`.
+        filename (str, optional):
+            A filename to be uploaded to a sidex server. This
+            argument is only required in the 'put' method.
+        token (str, optional):
+            A token string passed to a sidex server. This argument will
+            be ignored when the server is not protecte by token.
+
+    Returns:
+        requests.Response:
+                A response from a sidex server.
+    '''
+    method = 'get'
+
+    if method not in ('get', 'put', 'delete'):
+        raise RuntimeError('invalid method.')
+    if method == 'put' and filename is None:
+        raise RuntimeError('upload file is not specified.')
+    data = {'method': method, 'token': token}
+
+    if method == 'get':
+        if os.path.exists(filename):
+            raise RuntimeError('file "{}" already exists'.format(filename))
+        return requests.post(url, data=data)
+    elif method == 'put':
+        with open(filename, 'rb') as f:
+            files = {
+                'payload': f.read(),
+            }
+        return requests.post(url, data=data, files=files)
+    elif method == 'delete':
+        return requests.post(url, data=data)

sidex/server.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+''' A command-line SIDEX server.
+
+This file provides a command-line SIDEX server.
+A detailed usage is available by typing the following command:
+
+    python -m sidex.server -h
+'''
+
+from . setup import setup
+
+
+if __name__ == '__main__':
+    from argparse import ArgumentParser as ap
+    import logging
+    parser = ap(prog='server', description='sidex server process')
+    parser.add_argument(
+        'target', type=str,
+        help='target directory')
+    parser.add_argument(
+        '--host', metavar='host', type=str, default='0.0.0.0',
+        help='set server hostname')
+    parser.add_argument(
+        '--port', metavar='port', type=int, default=8080,
+        help='set server port number')
+    parser.add_argument(
+        '--get-token', metavar='token', type=str,
+        help='limit get function by setting token')
+    parser.add_argument(
+        '--put-token', metavar='token', type=str,
+        help='enable put function by setting token')
+    parser.add_argument(
+        '--delete-token', metavar='token', type=str,
+        help='enable delete function by setting token.')
+    parser.add_argument(
+        '--subdir', metavar='subdir', type=str,
+        help='set subdirectory')
+    parser.add_argument(
+        '--debug', action='store_true',
+        help='enable debug messages')
+
+    args = parser.parse_args()
+
+    log_level = 'DEBUG' if args.debug else 'INFO'
+    log_handler = logging.StreamHandler()
+    log_handler.setFormatter(logging.Formatter(
+        fmt='[%(asctime)s] %(levelname)s:%(name)s:%(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'))
+
+    server = setup(
+        args.target, subdir=args.subdir,
+        get_token=args.get_token, put_token=args.put_token,
+        delete_token=args.delete_token,
+        log_handler=log_handler, log_level=log_level)
+    server.run(host=args.host, port=args.port, threaded=True, debug=args.debug)

sidex/setup.py

@@ -0,0 +1,674 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+''' SIDEX miscellaneous functions.
+
+This module provides miscellaneous functions to setup the SIDEX server.
+The behaviours of the `get`, `put`, and `delete` methods are defined.
+
+Use the `setup` function to launch a customized SIDEX server.
+'''
+from flask import Flask, Response
+from flask import request, url_for
+import os, io, tarfile, logging
+
+werkzeug = logging.getLogger('werkzeug')
+werkzeug.setLevel('ERROR')
+
+app = Flask(__name__)
+
+
+@app.context_processor
+def override_url_for():
+    ''' A helper function to construct a url with `subdir` option.
+
+    This does nothing when the `subdir` option is not defined.
+    The url is modified in case that the `subdir` is given. The modified
+    `url_for` function accepts the following arguments.
+
+    Arguments:
+        endpoint (str):
+            The relative path to the requested resource.
+        *Arguments:
+            Variable length argument list.
+        **options:
+            Arbitrary option arguments.
+
+    Returns:
+        str: A constructed url to the requeste resource.
+    '''
+    def url_for_subdir(endpoint, *args, **options):
+        subdir = '/{}'.format(app.subdir) if app.subdir else ''
+        return subdir+url_for(endpoint, *args, **options)
+    return dict(url_for=url_for_subdir)
+
+
+def eprint(message, exc_info=None):
+    ''' Print an error message in the log file.
+
+    Arguments:
+        message (str):
+            The body of the error message.
+        exc_info (Exception,optional):
+            The Exception instance to print traceback information.
+    '''
+    remote = request.remote_addr
+    app.logger.error(remote+':{}'.format(message), exc_info=exc_info)
+
+
+def iprint(message):
+    ''' Print an info message in the log file.
+
+    Arguments:
+        message (str):
+            The body of the information message.
+    '''
+    remote = request.remote_addr
+    app.logger.info(remote+':{}'.format(message))
+
+
+def dprint(message):
+    ''' Print a debug message in the log file.
+
+    Arguments:
+        message (str):
+                The body of the debug message.
+    '''
+    remote = request.remote_addr
+    app.logger.debug(remote+':{}'.format(message))
+
+
+def invalid_path(path):
+    ''' Check whether the <path> looks invalid.
+
+    Arguments:
+        path (str):
+            The path to the file to be checked.
+
+    Returns:
+        bool:
+            `true` when the <path> contains any invalid sequences.
+    '''
+    return '../' in path
+
+
+def default_delete_function(req, local_path, **options):
+    ''' Define the default behavior of the `delete` method.
+
+    This function removes the file located at <local_path>.
+
+    Arguments:
+        req (flask.request):
+            The request instance given by Flask.
+        local_path (str):
+            The absolute path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+                A response message.
+    '''
+    filename = os.path.basename(local_path)
+    os.unlink(local_path)
+    return Response('"{}" successfully deleted.\n'.format(filename))
+
+
+def delete(req, target, **options):
+    ''' Provide the `delete` method.
+
+    This function is called when the `delete` method is selected.
+    The <app.delete_function> is called internally. When the customized
+    `delete_function` is specified, the behavior of the `delete` method
+    is overridden.
+
+    This method is disabled by default. To enable the `delete` method,
+    the application should be setup with `delete_token`. The token is
+    reffered to as <app.delete_token>.
+
+    The request must contain the `token` field. When the `token` is not
+    available, this always returns an error message.
+    In case that the `token` does not equal to <app.delete_token>,
+    an error message will be returned.
+
+    Arguments:
+        req (flask.request):
+            A request instance generated by Flask.
+        target (str):
+            The path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    local_path = '{}/{}'.format(app.workdir, target)
+    filename = os.path.basename(local_path)
+    dirname = os.path.dirname(local_path)
+    emsg = lambda s: 'cannot delete "{}": {{}}.\n'.format(target).format(s)
+    # check if a valid token is given.
+    if app.delete_token is None:
+        eprint('disabled function "delete" called.')
+        return Response(emsg('function disabled'), status=400)
+    token = req.form.get('token')
+    dprint('token = "{}"'.format(token))
+    if app.delete_token is not None and token != app.delete_token:
+        return Response(emsg('invalid token'), status=400)
+    # assert path seems valid.
+    if invalid_path(target):
+        eprint('invalid path: {}'.format(target))
+        return Response(emsg('invalid path'), status=400)
+    # delete a file.
+    try:
+        return app.delete_function(req, local_path, **options)
+    except FileNotFoundError as e:
+        eprint(str(e))
+        return Response(emsg('file not found'), status=404)
+    except Exception as e:
+        eprint(str(e))
+        errmsg = emsg(f'unexpected error: {str(e)} ({e.__class__.__name__})')
+        return Response(errmsg, status=500)
+
+
+def default_put_function(req, local_path, **options):
+    ''' Define the default behavior of the `put` method.
+
+    This function create a file stored in <req> at <local_path>.
+    This fails when the local directory does not exist. Note that
+    any existing file cannot be overwritten.
+
+    Arguments:
+        req (flask.request):
+            The request instance given by Flask.
+        local_path (str):
+            The absolute path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    filename = os.path.basename(local_path)
+    dirname = os.path.dirname(local_path)
+    req.files['payload'].save(local_path)
+    return Response('successfully uploaded to "{}".\n'.format(filename))
+
+
+def put(req, target, **options):
+    ''' Provide the `put` method.
+
+    This function is called when the `put` method is selected.
+    The <app.put_function> is called internally. When the customized
+    `put_function` is specified, the behavior of the `put` method
+    is overridden.
+
+    This method is disabled by default. To enable the `put` method,
+    the application should be setup with `put_token`. The token is
+    reffered to as <app.put_token>.
+
+    The request must contain the `token` field. When the `token` is not
+    available, this always returns an error message.
+    In case that the `token` does not equal to <app.put_token>,
+    an error message will be returned.
+
+    Arguments:
+        req (flask.request):
+            A request instance generated by Flask.
+        target (str):
+            The path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+                A response message.
+    '''
+    local_path = '{}/{}'.format(app.workdir, target)
+    filename = os.path.basename(local_path)
+    emsg = lambda s: 'cannot create "{}": {{}}.\n'.format(target).format(s)
+    # check if a valid token is given.
+    if app.put_token is None:
+        eprint('disabled function "put" called.')
+        return Response(emsg('function disabled'), status=400)
+    token = req.form.get('token')
+    dprint('token = "{}"'.format(token))
+    if app.put_token is not None and token != app.put_token:
+        return Response(emsg('invalid token'), status=400)
+    # assert path seems valid.
+    if invalid_path(target):
+        eprint('invalid path: {}'.format(target))
+        return Response(emsg('invalid path'), status=400)
+    # overwrite is not allowed.
+    if os.path.exists(local_path):
+        eprint('file "{}" already exists.'.format(local_path))
+        return Response(emsg('cannot overwrite files'), status=400)
+    # create a file.
+    if 'payload' not in req.files:
+        return Response(emsg('"payload" is required'), status=400)
+    try:
+        return app.put_function(req, local_path, **options)
+    except FileNotFoundError as e:
+        eprint(str(e))
+        return Response(emsg('file not found'), status=404)
+    except Exception as e:
+        eprint(str(e))
+        errmsg = emsg(f'unexpected error: {str(e)} ({e.__class__.__name__})')
+        return Response(errmsg, status=500)
+
+
+def default_get_function(req, local_path, **options):
+    ''' Define the default behavior of the `get` method.
+
+    Returns the file content located at <local_path>.
+
+    Arguments:
+        req (flask.request):
+            The request instance given by Flask.
+        local_path (str):
+            The absolute path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    with open(local_path, 'rb') as f:
+        return Response(f.read(), mimetype='application/octet-stream')
+
+
+def streaming_get_function(req, local_path, **options):
+    ''' Define the streaming version of the `get` method.
+
+    Returns the file content located at <local_path>.
+
+    Arguments:
+        req (flask.request):
+            The request instance given by Flask.
+        local_path (str):
+            The absolute path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    bufsize = options.get('bufsize', 65535)
+
+    def is_active(FileStream):
+        b = FileStream.read(1)
+        FileStream.seek(-1, 1)
+        return bool(b)
+
+    def streaming():
+        with open(local_path, 'rb') as f:
+            while is_active(f):
+                yield f.read(bufsize)
+
+    return Response(streaming(), mimetype='application/octet-stream')
+
+
+def get(req, target, **options):
+    ''' Provide the `get` method.
+
+    This function is called when the `get` method is selected.
+    The <app.get_function> is called internally. When the customized
+    `get_function` is specified, the behavior of the `get` method
+    is overridden.
+
+    This method can be protected by setting `get_token`. The token is
+    reffered to as <app.get_token>. When <app.get_token> is defined,
+    the request must contain the `token` field.
+    In case that the `token` does not equal to <app.get_token>,
+    an error message will be returned.
+
+    Arguments:
+        req (flask.request):
+            A request instance generated by Flask.
+        target (str):
+            The path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    local_path = '{}/{}'.format(app.workdir, target)
+    filename = os.path.basename(local_path)
+    emsg = lambda s: 'cannot access "{}": {{}}.\n'.format(target).format(s)
+    # check if a valid token is given.
+    if app.get_token is not None:
+        dprint('"get" function requres a token.')
+        token = req.form.get('token')
+        dprint('token = "{}"'.format(token))
+        if token != app.get_token:
+            return Response(emsg('invalid token'), status=400)
+    # assert path seems valid.
+    if invalid_path(target):
+        eprint('invalid path: {}'.format(target))
+        return Response(emsg('invalid path'), status=500)
+    # access to file.
+    try:
+        return app.get_function(req, local_path, **options)
+    except FileNotFoundError as e:
+        eprint(str(e))
+        return Response(emsg('file not found'), status=404)
+    except IsADirectoryError as e:
+        eprint(str(e))
+        return Response(emsg('cannot obtain directory'), status=400)
+    except Exception as e:
+        eprint(str(e))
+        errmsg = emsg(f'unexpected error: {str(e)} ({e.__class__.__name__})')
+        return Response(errmsg, status=500)
+
+
+def default_dump_function(req, local_paths, **options):
+    ''' Define the default behavior of the `dump` method.
+
+    Returns the file content located at <local_path>.
+
+    Arguments:
+        req (flask.request):
+            The request instance given by Flask.
+        local_paths (list):
+            The list of the absolute paths to the requested resources.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+                A response message.
+    '''
+    def streaming():
+        buf = io.BytesIO()
+        with tarfile.open(fileobj=buf, mode='w') as arv:
+            for filename in local_paths:
+                pos = buf.tell()
+                basename = os.path.basename(filename)
+                arv.add(filename, arcname=basename)
+                buf.seek(pos)
+                yield buf.read()
+                # the stream position should be set something but zero.
+                # an init process is called when the stream position is zero.
+                buf.seek(1)
+                buf.truncate(1)
+    return Response(streaming(), mimetype='application/octet-stream')
+
+
+def dump(req, filelist, **options):
+    ''' Provide the `dump` method.
+
+    This function is called when the `dump` method is selected.
+    The <app.dump_function> is called internally. When the customized
+    `dump_function` is specified, the behavior of the `dump` method
+    is overridden.
+
+    This method can be protected by setting `get_token`. The token is
+    reffered to as <app.get_token>. When <app.get_token> is defined,
+    the request must contain the `token` field.
+    In case that the `token` does not equal to <app.get_token>,
+    an error message will be returned.
+
+    Arguments:
+        req (flask.request):
+            A request instance generated by Flask.
+        filelist (list):
+            The list of the paths to the requested resources.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+                A response message.
+    '''
+    local_paths = ['{}/{}'.format(app.workdir, f) for f in filelist]
+    filenames = [os.path.basename(p) for p in local_paths]
+    emsg = lambda s: 'cannot access resources: {}.\n'.format(s)
+    # check if a valid token is given.
+    if app.get_token is not None:
+        dprint('"get" function requres a token.')
+        token = req.form.get('token')
+        dprint('token = "{}"'.format(token))
+        if token != app.get_token:
+            return Response(emsg('invalid token'), status=400)
+    # assert path seems valid.
+    for target in filelist:
+        if invalid_path(target):
+            eprint('invalid path: {}'.format(target))
+            return Response(emsg('invalid path'), status=500)
+    # access to file.
+    try:
+        return app.dump_function(req, local_paths, **options)
+    except FileNotFoundError as e:
+        eprint(str(e))
+        return Response(emsg('file not found'), status=404)
+    except IsADirectoryError as e:
+        eprint(str(e))
+        return Response(emsg('cannot obtain directory'), status=400)
+    except Exception as e:
+        eprint(str(e))
+        errmsg = emsg(f'unexpected error: {str(e)} ({e.__class__.__name__})')
+        return Response(errmsg, status=500)
+
+
+def default_ping_function(req, local_path, **options):
+    ''' Define the default behavior of the `ping` method.
+
+    Returns True if the the requested file exists at <local_path>.
+
+    Arguments:
+        req (flask.request):
+            The request instance given by Flask.
+        local_path (str):
+            The absolute paths to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    if os.path.exists(local_path):
+        return Response('', 200)
+    else:
+        raise FileNotFoundError(local_path)
+
+
+def ping(req, target, **options):
+    ''' Provide the `ping` method.
+
+    This function is called when the `ping` method is selected.
+    The <app.ping_function> is called internally. When the customized
+    `ping_function` is specified, the behavior of the `ping` method
+    is overridden.
+
+    This method can be protected by setting `get_token`. The token is
+    reffered to as <app.get_token>. When <app.get_token> is defined,
+    the request must contain the `token` field.
+    In case that the `token` does not equal to <app.get_token>,
+    an error message will be returned.
+
+    Arguments:
+        req (flask.request):
+            A request instance generated by Flask.
+        target (str):
+            The path to the requested resource.
+        **options:
+            Arbitrary option arguments.
+            Currently no option is passed to this function.
+
+    Returns:
+        flask.Response:
+            A response message.
+    '''
+    local_path = '{}/{}'.format(app.workdir, target)
+    filename = os.path.basename(local_path)
+    emsg = lambda s: 'cannot access "{}": {{}}.\n'.format(target).format(s)
+    # check if a valid token is given.
+    if app.get_token is not None:
+        dprint('"get" function requres a token.')
+        token = req.form.get('token')
+        dprint('token = "{}"'.format(token))
+        if token != app.get_token:
+            return Response(emsg('invalid token'), status=400)
+    # assert path seems valid.
+    if invalid_path(target):
+        eprint('invalid path: {}'.format(target))
+        return Response(emsg('invalid path'), status=500)
+    # access to file.
+    try:
+        return app.ping_function(req, local_path, **options)
+    except FileNotFoundError as e:
+        eprint(str(e))
+        return Response(emsg('file/directory not found'), status=404)
+    except Exception as e:
+        eprint(str(e))
+        errmsg = emsg(f'unexpected error: {str(e)} ({e.__class__.__name__})')
+        return Response(errmsg, status=500)
+
+
+@app.route('/<path:target>', methods=['GET', ])
+def access_by_get(target):
+    ''' The access point of the SIDEX server.
+
+    This function handles the GET request to the SIDEX server.
+    This works only if the `token` is not specified.
+
+    Arguments:
+        target (str):
+            The path to the requested resource.
+
+    Returns:
+        flask.Response:
+            The response instance from the requested method.
+    '''
+    return get(request, target)
+
+
+@app.route('/<path:target>', methods=['POST', ])
+def access_get_by_post(target):
+    ''' The access point of the SIDEX server.
+
+    This function handles the POST request to the SIDEX server.
+    The `method` field is mandatory. The value should be one of `get`,
+    `put` and `delete`. The corresponding function will be called.
+
+    The `token` field is required in the `put` and `delete` methods.
+
+    Arguments:
+        target (str):
+            The path to the requested resource.
+
+    Returns:
+        flask.Response:
+            The response instance from the requested method.
+    '''
+    method = request.form.get('method', 'none').lower()
+    if method == 'get':
+        return get(request, target)
+    elif method == 'put':
+        return put(request, target)
+    elif method == 'delete':
+        return delete(request, target)
+    elif method == 'ping':
+        return ping(request, target)
+    else:
+        return Response('invalid method: {}.\n'.format(method), status=400)
+
+
+@app.route('/', methods=['GET', 'POST'])
+def root():
+    if request.method == 'GET':
+        return Response('It works! The SIDEX server is running.\n')
+    else:
+        method = request.form.get('method', 'none').lower()
+        if method == 'dump':
+            filenames = request.form.getlist('filename')
+            return dump(request, filenames)
+        else:
+            return Response('invalid method: {}.\n'.format(method), status=400)
+
+
+def setup(
+        workdir, subdir=None,
+        get_function=default_get_function,
+        put_function=default_put_function,
+        delete_function=default_delete_function,
+        dump_function=default_dump_function,
+        ping_function=default_ping_function,
+        get_token=None, put_token=None, delete_token=None,
+        log_handler=None, log_level='INFO'):
+    ''' Setup a customized SIDEX server.
+
+    Arguments:
+        workdir (str):
+            The relative path to the working directory.
+        subdir (str,optional):
+            The name of the subdirectory.
+        get_function (function,optional):
+            The function instance called in the `get` method.
+            The following arguments are required:
+                - req (flask.request): The flask request instance.
+                - local_path (str): The local path to the resource.
+        put_function (function,optional):
+            The function instance called in the `put` method.
+            The following arguments are required:
+                - req (flask.request): The flask request instance.
+                - local_path (str): The local path to the resource.
+        delete_function (function,optional):
+            The function instance called in the `delete` method.
+            The following arguments are required:
+                - req (flask.request): The flask request instance.
+                - local_path (str): The local path to the resource.
+        dump_function (function,optional):
+            The function instance called in the `dump` method.
+            The following arguments are required:
+                - req (flask.request): The flask request instance.
+                - local_paths (list): The path list to the resources.
+        ping_function (function,optional):
+            The function instance called in the `ping` method.
+            The following arguments are required:
+                - req (flask,request): The flask request instance.
+                - local_path (str): The local path to the resource.
+        get_token (str,optional):
+            The secret token for the `get` method.
+        put_token (str,optional):
+            The secret token for the `put` method.
+        delete_token (str,optional):
+            The secret token for the `delete` method.
+        log_handler (logger.Logger,optional):
+            The user-defined log handler to override the default handler.
+        log_level (str,optional):
+            The log_level. `INFO` is given by default.
+    '''
+    if get_token is not None: assert len(get_token) > 0
+    if put_token is not None: assert len(put_token) > 0
+    if delete_token is not None: assert len(delete_token) > 0
+    app.workdir = workdir
+    app.get_function = get_function
+    app.put_function = put_function
+    app.delete_function = delete_function
+    app.dump_function = dump_function
+    app.ping_function = ping_function
+    app.get_token = get_token
+    app.put_token = put_token
+    app.delete_token = delete_token
+    app.subdir = subdir
+    app.logger.setLevel(log_level)
+    if log_handler is not None:
+        werkzeug.handlers = []
+        app.logger.handlers = [log_handler, ]
+    return app

sidex-1.5.1.dist-info/METADATA

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: sidex
+Version: 1.5.1
+Summary: SIDEX: Simple Data Exchange server over HTTP
+Author-email: Ryou Ohsawa <ryou.ohsawa@nao.ac.jp>
+Maintainer-email: Ryou Ohsawa <ryou.ohsawa@nao.ac.jp>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/astronasutarou/sidex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=2.0
+Requires-Dist: requests>=2.27
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CodeQL](https://github.com/astronasutarou/sidex/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/astronasutarou/sidex/actions/workflows/github-code-scanning/codeql)
+[![Documentation Status](https://readthedocs.org/projects/sidex/badge/?version=latest)](https://sidex.readthedocs.io/en/latest/?badge=latest)
+
+# Simple Data Exchange server over HTTP
+
+## Overview
+This package provides a function to launch a simple file server. Getting, putting, and deleting files on the server via the HTTP POST methods are available. The function `setup_sidex()` returns a `flask` instance. You can launch a simple file server by `run()`.
+
+``` python
+from sidex import setup_sidex
+
+target = '/path/to/directory'
+app = setup_sidex(target)
+app.run()
+```
+
+Otherwise, you can directly call `sidex.server`.
+
+``` sh
+$ python -m sidex.server /path/to/directory
+```
+
+By default, only retrieving files (`get`) is available. The `put` and `delete` methods are enabled by setting a 'token' for each method. Of course, the `get` function can be restricted by a `token`.
+
+The HTTP POST method is available to submit a request. Any request should contain the `method` field, which should be one of `get`, `put`, and `delete`. The `token` field may be required in some cases. The followings are samples with `curl`.
+
+``` sh
+$ curl http://0.0.0.0:8080/path/to/file -F 'method=get'
+$ curl http://0.0.0.0:8080/path/to/upload -F 'method=put' -F 'payload=@filename' -F 'token=foo'
+$ curl http://0.0.0.0:8080/path/to/delete -F 'method=delete' -F 'token=bar'
+```
+
+The package provides a function, `sidex_request()`, which is a wrapper function of `requests.post()`. You can directly execute `sidex.client`.
+
+``` sh
+$ python -m sidex.client http://0.0.0.0:8080/path/to/file
+$ python -m sidex.client http://0.0.0.0:8080/path/to/file --ping
+$ python -m sidex.client http://0.0.0.0:8080/path/to/upload -f upload_file
+$ python -m sidex.client http://0.0.0.0:8080/path/to/delete -d
+```
+
+
+## Dependencies
+The library is developed on Python 3.9.9. The following packages are required:
+
+``` python
+flask>=2.0
+requests>=2.27
+```

sidex-1.5.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+sidex/__init__.py,sha256=FHqXfZ3IwQBfmTzcI_3NdVUzPgQJJ8smrsDRUmHvTQc,1205
+sidex/client.py,sha256=aM34SdBhXUf7e7glkuaFpJj8LlD29O1Iu5oLhJm9Y84,2228
+sidex/dump.py,sha256=cHT5-ghfrImOU6ZM1U5m002OQIFl7_6CUDQJVYceENM,2782
+sidex/request.py,sha256=6RXQg3ldZZqOOzyS4agbtI0sOcz2fAvBMnYoBj-staU,1680
+sidex/server.py,sha256=IoG8oHS7xGRCRlZ6McAC7GWxeFTAGo3Uyii7VU1vqYk,1916
+sidex/setup.py,sha256=SEDinX8t3W2PZjF7tdMZ9kkqeRRhtb8jLlk-uu7R9Z4,23511
+sidex-1.5.1.dist-info/METADATA,sha256=2xOF5oGCf3qOYqyRMT1AFtEEjPEmC4X2qELhCIMkzr0,3059
+sidex-1.5.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sidex-1.5.1.dist-info/top_level.txt,sha256=9gw4MnFmjW8UkjL-AZPLbc-9jAuNPFxn9bc_guBVPwE,17
+sidex-1.5.1.dist-info/RECORD,,

sidex-1.5.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sidex-1.5.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+build
+docs
+sidex