Helper Examples
===============

getFileMappings
---------------

    Example:
        .. code-block:: python

            from jetstream.helper import Helper

            files = ['/repo/project/readme.txt', '/repo/project/build/make', '/repo/project/src/main.cpp']

            helper = Helper(None)
            helper.getFileMappings(files)
            # {'/repo/project/build/make': '/repo/project/build/make',
            #  '/repo/project/readme.txt': '/repo/project/readme.txt',
            #  '/repo/project/src/main.cpp': '/repo/project/src/main.cpp'}

            helper.getFileMappings(files, relative_to='/repo/project')
            # {'/repo/project/build/make': 'build/make',
            #  '/repo/project/readme.txt': 'readme.txt',
            #  '/repo/project/src/main.cpp': 'src/main.cpp'}

getFilteredManifestFiles
------------------------

    Example:
        .. code-block:: python

            from jetstream import JetStream
            from jetstream.helper import Helper

            def _text_files(fileMappings):
                return fileMappings['srcPath'].endswith('.txt')

            jetstream = JetStream()
            api = jetstream.api()
            api.connect()

            helper = Helper(api)
            # Submit the predicate to getFilteredManifestFiles().
            manifests = helper.getFilteredManifestFiles(_text_files)
            # {'errorMessage': None,
            # 'fileMappings': [{'destPath': 'setup/README.txt',
            #                   'fileSize': 183,
            #                   'isEmptyDir': False,
            #                   'srcPath': '/depot/project/setup/README.txt'},
            #                  {'destPath': 'docs/requirements.txt',
            #                   'fileSize': 2238,
            #                   'isEmptyDir': False,
            #                   'srcPath': '/depot/project/docs/requirements.txt'}],
            # 'manifestId': '3dcbe0ef1bb143ad0100000000000003',
            # 'processing': False,
            # 'status': 'complete',
            # 'totalFiles': 195,
            # 'totalSize': 6428287}]

    Example:
        .. code-block:: python

            def find_file_by_name(name):
                # Use a case-insensitive regular expression.
                _r = re.compile(name, re.I)
                # Define a predicate that compares 'srcPath'
                _fltr = lambda fileMappings: _r.search(fileMappings['srcPath'])
                with JetStream().api() as api:
                    helper = Helper(api)
                    # Submit the predicate to getFilteredManifestFiles().
                    manifests = helper.getFilteredManifestFiles(_fltr)
                return manifests

            find_file_by_name('index.html')
            # [{'errorMessage': None,
            # 'fileMappings': [{'destPath': '/docs/_build/html/index.html',
            #                   'fileSize': 14373,
            #                   'isEmptyDir': False,
            #                   'srcPath': '/project/serendipity/docs/_build/html/index.html'}],
            # 'manifestId': '3dcbe0ef1bb143ad0100000000000011',
            # 'processing': False,
            # 'status': 'complete',
            # 'totalFiles': 647,
            # 'totalSize': 245631984}]

getTransferFlags
----------------

    Example:
        .. code-block:: python

            from jetstream.helper import Helper

            helper = Helper(None)
            helper.getTransferFlags(readEnabled=True, writeEnabled=True)
            # 3
            helper.getTransferFlags(readEnabled=True, writeEnabled=False)
            # 1

sendFiles
---------

    Example:
        .. code-block:: python

            import getpass
            from jetstream import JetStream
            from jetstream.helper import Helper

            jetstream = JetStream()
            api = jetstream.api()
            api.connect()
            destination = api.send.createDestination("localhost", sendRateMax=12345)

            helper = Helper(api)

            sourcePath = '/path/to/local/file.txt'
            destinationPath = 'uploads'
            transferObject = helper.sendFiles(destination, sourcePath, destinationPath, userName=getpass.getuser(), password=getpass.getpass())

            progress = transferObject.getProgress()
            status = transferObject.getStatus()
            transfer = transferObject.getRawStats()

