Instruction:
Implement a function in Python 3 to
copy file from source to destination.

Response:
def _copy(src, dst, src_is_storage, dst_is_storage):
    """
    Copies file from source to destination

    Args:
        src (str or file-like object): Source file.
        dst (str or file-like object): Destination file.
        src_is_storage (bool): Source is storage.
        dst_is_storage (bool): Destination is storage.
    """
    # If both storage: Tries to perform same storage direct copy
    if src_is_storage and dst_is_storage:
        system_src = get_instance(src)
        system_dst = get_instance(dst)

        # Same storage copy
        if system_src is system_dst:

            # Checks if same file
            if system_src.relpath(src) == system_dst.relpath(dst):
                raise same_file_error(
                    "'%s' and '%s' are the same file" % (src, dst))

            # Tries to copy
            try:
                return system_dst.copy(src, dst)
            except (UnsupportedOperation, ObjectException):
                pass

        # Copy from compatible storage using "copy_from_<src_storage>" or
        # "copy_to_<src_storage>" method if any
        for caller, called, method in (
                (system_dst, system_src, 'copy_from_%s'),
                (system_src, system_dst, 'copy_to_%s')):
            if hasattr(caller, method % called.storage):
                try:
                    return getattr(caller, method % called.storage)(
                        src, dst, called)
                except (UnsupportedOperation, ObjectException):
                    continue

    # At least one storage object: copies streams
    with cos_open(src, 'rb') as fsrc:
        with cos_open(dst, 'wb') as fdst:

            # Get stream buffer size
            for stream in (fsrc, fdst):
                try:
                    buffer_size = getattr(stream, '_buffer_size')
                    break
                except AttributeError:
                    continue
            else:
                buffer_size = COPY_BUFSIZE

            # Read and write
            copyfileobj(fsrc, fdst, buffer_size)


Instruction:
Here you have a function in Python 3, explain what it does
def copy(src, dst):
    # Handles path-like objects and checks if storage
    src, src_is_storage = format_and_is_storage(src)
    dst, dst_is_storage = format_and_is_storage(dst)

    # Local files: Redirects to "shutil.copy"
    if not src_is_storage and not dst_is_storage:
        return shutil_copy(src, dst)

    with handle_os_exceptions():
        # Checks destination
        if not hasattr(dst, 'read'):
            try:
                # If destination is directory: defines an output file inside it
                if isdir(dst):
                    dst = join(dst, basename(src))

                # Checks if destination dir exists
                elif not isdir(dirname(dst)):
                    raise IOError("No such file or directory: '%s'" % dst)

            except ObjectPermissionError:
                # Unable to check target directory due to missing read access,
                # but do not raise to allow to write if possible
                pass

        # Performs copy
        _copy(src, dst, src_is_storage, dst_is_storage)

Response: Copies a source file to a destination file or directory.


Instruction:
Can you tell what is the following Python 3 function doing
def copyfile(src, dst, follow_symlinks=True):
    # Handles path-like objects and checks if storage
    src, src_is_storage = format_and_is_storage(src)
    dst, dst_is_storage = format_and_is_storage(dst)

    # Local files: Redirects to "shutil.copyfile"
    if not src_is_storage and not dst_is_storage:
        return shutil_copyfile(src, dst, follow_symlinks=follow_symlinks)

    with handle_os_exceptions():
        # Checks destination
        try:
            if not hasattr(dst, 'read') and not isdir(dirname(dst)):
                raise IOError("No such file or directory: '%s'" % dst)

        except ObjectPermissionError:
            # Unable to check target directory due to missing read access, but
            # do not raise to allow to write if possible
            pass

        # Performs copy
        _copy(src, dst, src_is_storage, dst_is_storage)

Response: Copies a source file to a destination file.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _handle_client_error():
    try:
        yield

    except _ClientError as exception:
        error = exception.response['Error']
        if error['Code'] in _ERROR_CODES:
            raise _ERROR_CODES[error['Code']](error['Message'])
        raise

Response:
Handle boto exception and convert to class
    IO exceptions


Instruction:
Implement a Python 3 function for
copying object of the same storage.

Response:
def copy(self, src, dst, other_system=None):
        """
        Copy object of the same storage.

        Args:
            src (str): Path or URL.
            dst (str): Path or URL.
            other_system (pycosio._core.io_system.SystemBase subclass): Unused.
        """
        copy_source = self.get_client_kwargs(src)
        copy_destination = self.get_client_kwargs(dst)
        with _handle_client_error():
            self.client.copy_object(CopySource=copy_source, **copy_destination)


Instruction:
Can you create a Python 3 function that
gets base keyword arguments for a specific path.

Response:
def get_client_kwargs(self, path):
        """
        Get base keyword arguments for client for a
        specific path.

        Args:
            path (str): Absolute path or URL.

        Returns:
            dict: client args
        """
        bucket_name, key = self.split_locator(path)
        kwargs = dict(Bucket=bucket_name)
        if key:
            kwargs['Key'] = key
        return kwargs


Instruction:
Can you tell what is the following Python 3 function doing
def _get_session(self):
        if self._session is None:
            self._session = _boto3.session.Session(
                **self._storage_parameters.get('session', dict()))
        return self._session

Response: Returns a boto3. session. Session object.


Instruction:
Make a summary of the following Python 3 code
def _get_client(self):
        client_kwargs = self._storage_parameters.get('client', dict())

        # Handles unsecure mode
        if self._unsecure:
            client_kwargs = client_kwargs.copy()
            client_kwargs['use_ssl'] = False

        return self._get_session().client("s3", **client_kwargs)

Response: Get the client object for the current object.


Instruction:
Create a Python 3 function for
returning the URL roots for this storage.

Response:
def _get_roots(self):
        """
        Return URL roots for this storage.

        Returns:
            tuple of str or re.Pattern: URL roots
        """
        region = self._get_session().region_name or r'[\w-]+'
        return (
                # S3 scheme
                # - s3://<bucket>/<key>
                's3://',

                # Virtual-hosted–style URL
                # - http://<bucket>.s3.amazonaws.com/<key>
                # - https://<bucket>.s3.amazonaws.com/<key>
                # - http://<bucket>.s3-<region>.amazonaws.com/<key>
                # - https://<bucket>.s3-<region>.amazonaws.com/<key>
                _re.compile(r'https?://[\w.-]+\.s3\.amazonaws\.com'),
                _re.compile(
                    r'https?://[\w.-]+\.s3-%s\.amazonaws\.com' % region),

                # Path-hosted–style URL
                # - http://s3.amazonaws.com/<bucket>/<key>
                # - https://s3.amazonaws.com/<bucket>/<key>
                # - http://s3-<region>.amazonaws.com/<bucket>/<key>
                # - https://s3-<region>.amazonaws.com/<bucket>/<key>
                _re.compile(r'https?://s3\.amazonaws\.com'),
                _re.compile(r'https?://s3-%s\.amazonaws\.com' % region),

                # Transfer acceleration URL
                # - http://<bucket>.s3-accelerate.amazonaws.com
                # - https://<bucket>.s3-accelerate.amazonaws.com
                # - http://<bucket>.s3-accelerate.dualstack.amazonaws.com
                # - https://<bucket>.s3-accelerate.dualstack.amazonaws.com
                _re.compile(
                    r'https?://[\w.-]+\.s3-accelerate\.amazonaws\.com'),
                _re.compile(
                    r'https?://[\w.-]+\.s3-accelerate\.dualstack'
                    r'\.amazonaws\.com'))


Instruction:
Given the following Python 3 function, write the documentation
def _get_time(header, keys, name):
        for key in keys:
            try:
                return _to_timestamp(header.pop(key))
            except KeyError:
                continue
        raise _UnsupportedOperation(name)

Response: Get time from header


Instruction:
Implement a function in Python 3 to
return object or bucket HTTP header.

Response:
def _head(self, client_kwargs):
        """
        Returns object or bucket HTTP header.

        Args:
            client_kwargs (dict): Client arguments.

        Returns:
            dict: HTTP header.
        """
        with _handle_client_error():
            # Object
            if 'Key' in client_kwargs:
                header = self.client.head_object(**client_kwargs)

            # Bucket
            else:
                header = self.client.head_bucket(**client_kwargs)

        # Clean up HTTP request information
        for key in ('AcceptRanges', 'ResponseMetadata'):
            header.pop(key, None)
        return header


Instruction:
How would you implement a function in Python 3 that
makes a directory. args: client_kwargs (dict): Client arguments.

Response:
def _make_dir(self, client_kwargs):
        """
        Make a directory.

        args:
            client_kwargs (dict): Client arguments.
        """
        with _handle_client_error():
            # Object
            if 'Key' in client_kwargs:
                return self.client.put_object(Body=b'', **client_kwargs)

            # Bucket
            return self.client.create_bucket(
                Bucket=client_kwargs['Bucket'],
                CreateBucketConfiguration=dict(
                    LocationConstraint=self._get_session().region_name))


Instruction:
Write a Python 3 function that can
remove an object from the cache.

Response:
def _remove(self, client_kwargs):
        """
        Remove an object.

        args:
            client_kwargs (dict): Client arguments.
        """
        with _handle_client_error():
            # Object
            if 'Key' in client_kwargs:
                return self.client.delete_object(**client_kwargs)

            # Bucket
            return self.client.delete_bucket(Bucket=client_kwargs['Bucket'])


Instruction:
Make a summary of the following Python 3 code
def _list_locators(self):
        with _handle_client_error():
            response = self.client.list_buckets()

        for bucket in response['Buckets']:
            yield bucket.pop('Name'), bucket

Response:
Lists locators.

        Returns:
            generator of tuple: locator name str, locator header dict


Instruction:
Can you generate the documentation for the following Python 3 function
def _list_objects(self, client_kwargs, path, max_request_entries):
        client_kwargs = client_kwargs.copy()
        if max_request_entries:
            client_kwargs['MaxKeys'] = max_request_entries

        while True:
            with _handle_client_error():
                response = self.client.list_objects_v2(
                    Prefix=path, **client_kwargs)

            try:
                for obj in response['Contents']:
                    yield obj.pop('Key'), obj
            except KeyError:
                raise _ObjectNotFoundError('Not found: %s' % path)

            # Handles results on more than one page
            try:
                client_kwargs['ContinuationToken'] = response[
                    'NextContinuationToken']
            except KeyError:
                # End of results
                break

Response: A generator function that returns objects from the object store.


Instruction:
Explain what the following Python 3 code does
def _read_range(self, start, end=0):
        # Get object part from S3
        try:
            with _handle_client_error():
                response = self._client.get_object(
                    Range=self._http_range(start, end), **self._client_kwargs)

        # Check for end of file
        except _ClientError as exception:
            if exception.response['Error']['Code'] == 'InvalidRange':
                # EOF
                return bytes()
            raise

        # Get object content
        return response['Body'].read()

Response: Read a range of bytes in stream.


Instruction:
Write a Python 3 function that can
flush the write buffers of the given buffer.

Response:
def _flush(self, buffer):
        """
        Flush the write buffers of the stream if applicable.

        Args:
            buffer (memoryview): Buffer content.
        """
        with _handle_client_error():
            self._client.put_object(
                Body=buffer.tobytes(), **self._client_kwargs)


Instruction:
Can you generate the documentation for the following Python 3 function
def _flush(self):
        # Initialize multi-part upload
        if 'UploadId' not in self._upload_args:
            with _handle_client_error():
                self._upload_args[
                    'UploadId'] = self._client.create_multipart_upload(
                    **self._client_kwargs)['UploadId']

        # Upload part with workers
        response = self._workers.submit(
            self._client.upload_part, Body=self._get_buffer().tobytes(),
            PartNumber=self._seek, **self._upload_args)

        # Save part information
        self._write_futures.append(
            dict(response=response, PartNumber=self._seek))

Response: Flush the write buffers of the stream.


Instruction:
Given the following Python 3 function, write the documentation
def _close_writable(self):
        # Wait parts upload completion
        for part in self._write_futures:
            part['ETag'] = part.pop('response').result()['ETag']

        # Complete multipart upload
        with _handle_client_error():
            try:
                self._client.complete_multipart_upload(
                    MultipartUpload={'Parts': self._write_futures},
                    UploadId=self._upload_args['UploadId'],
                    **self._client_kwargs)
            except _ClientError:
                # Clean up if failure
                self._client.abort_multipart_upload(
                    UploadId=self._upload_args['UploadId'],
                    **self._client_kwargs)
                raise

Response: Close the object in write mode.


Instruction:
Implement a Python 3 function for
handling Azure exception and convert to class IO exceptions

Response:
def _handle_azure_exception():
    """
    Handles Azure exception and convert to class IO exceptions

    Raises:
        OSError subclasses: IO error.
    """
    try:
        yield

    except _AzureHttpError as exception:
        if exception.status_code in _ERROR_CODES:
            raise _ERROR_CODES[exception.status_code](str(exception))
        raise


Instruction:
How would you explain what the following Python 3 function does
def _properties_model_to_dict(properties):
    result = {}
    for attr in properties.__dict__:
        value = getattr(properties, attr)

        if hasattr(value, '__module__') and 'models' in value.__module__:
            value = _properties_model_to_dict(value)

        if not (value is None or (isinstance(value, dict) and not value)):
            result[attr] = value

    return result

Response: Convert properties model to dict.


Instruction:
Given the following Python 3 function, write the documentation
def _get_endpoint(self, sub_domain):
        storage_parameters = self._storage_parameters or dict()
        account_name = storage_parameters.get('account_name')

        if not account_name:
            raise ValueError('"account_name" is required for Azure storage')

        suffix = storage_parameters.get(
            'endpoint_suffix', 'core.windows.net')

        self._endpoint = 'http%s://%s.%s.%s' % (
            '' if self._unsecure else 's', account_name, sub_domain, suffix)

        return account_name, suffix.replace('.', r'\.')

Response: Get endpoint information from storage parameters and update self. _endpoint


Instruction:
Here you have a function in Python 3, explain what it does
def _secured_storage_parameters(self):
        parameters = self._storage_parameters or dict()

        # Handles unsecure mode
        if self._unsecure:
            parameters = parameters.copy()
            parameters['protocol'] = 'http'

        return parameters

Response: Updates storage parameters with unsecure mode.


Instruction:
Can you write a function in Python 3 where it
formats path for cross Azure storage account copy function.

Response:
def _format_src_url(self, path, caller_system):
        """
        Ensure path is absolute and use the correct URL format for use with
        cross Azure storage account copy function.

        Args:
            path (str): Path or URL.
            caller_system (pycosio.storage.azure._AzureBaseSystem subclass):
                System calling this method (Can be another Azure system).

        Returns:
            str: URL.
        """
        path = '%s/%s' % (self._endpoint, self.relpath(path))

        # If SAS token available, use it to give cross account copy access.
        if caller_system is not self:
            try:
                path = '%s?%s' % (path, self._storage_parameters['sas_token'])
            except KeyError:
                pass

        return path


Instruction:
Make a summary of the following Python 3 code
def _update_listing_client_kwargs(client_kwargs, max_request_entries):
        client_kwargs = client_kwargs.copy()
        if max_request_entries:
            client_kwargs['num_results'] = max_request_entries
        return client_kwargs

Response: Updates the client kwargs for listing functions.


Instruction:
How would you implement a function in Python 3 that
converts object model to dict.

Response:
def _model_to_dict(obj):
        """
        Convert object model to dict.

        Args:
            obj: Object model.

        Returns:
            dict: Converted model.
        """
        result = _properties_model_to_dict(obj.properties)
        for attribute in ('metadata', 'snapshot'):
            try:
                value = getattr(obj, attribute)
            except AttributeError:
                continue
            if value:
                result[attribute] = value
        return result


Instruction:
Can you generate the documentation for the following Python 3 function
def _read_range(self, start, end=0):
        stream = _BytesIO()
        try:
            with _handle_azure_exception():
                self._get_to_stream(
                    stream=stream, start_range=start,
                    end_range=(end - 1) if end else None, **self._client_kwargs)

        # Check for end of file
        except _AzureHttpError as exception:
            if exception.status_code == 416:
                # EOF
                return bytes()
            raise

        return stream.getvalue()

Response: Reads a range of bytes in stream.


Instruction:
Create a Python 3 function for
reading and return all the bytes from the stream until EOF.

Response:
def _readall(self):
        """
        Read and return all the bytes from the stream until EOF.

        Returns:
            bytes: Object content
        """
        stream = _BytesIO()
        with _handle_azure_exception():
            self._get_to_stream(stream=stream, **self._client_kwargs)
        return stream.getvalue()


Instruction:
Can you generate the documentation for the following Python 3 function
def _init_append(self):
        if self._content_length:
            # Adjust size if content length specified
            with _handle_azure_exception():
                self._resize(
                    content_length=self._content_length, **self._client_kwargs)
                self._reset_head()

        # Make initial seek position to current end of file
        self._seek = self._size

Response: Initializes file on a mode.


Instruction:
Can you create a Python 3 function that
creates the file in Azure.

Response:
def _create(self):
        """
        Create the file if not exists.
        """
        # Create new file
        with _handle_azure_exception():
            self._create_from_size(
                content_length=self._content_length, **self._client_kwargs)


Instruction:
How would you code a function in Python 3 to
flush the buffer of the stream if applicable.

Response:
def _flush(self, buffer, start, end):
        """
        Flush the write buffer of the stream if applicable.

        Args:
            buffer (memoryview): Buffer content.
            start (int): Start of buffer position to flush.
                Supported only with page blobs.
            end (int): End of buffer position to flush.
                Supported only with page blobs.
        """
        buffer_size = len(buffer)
        if not buffer_size:
            return

        # Write range normally
        with self._size_lock:
            if end > self._size:
                # Require to resize the blob if note enough space
                with _handle_azure_exception():
                    self._resize(content_length=end, **self._client_kwargs)
                self._reset_head()

        if buffer_size > self.MAX_FLUSH_SIZE:
            # Too large buffer, needs to split in multiples requests
            futures = []
            for part_start in range(0, buffer_size, self.MAX_FLUSH_SIZE):

                # Split buffer
                buffer_part = buffer[
                      part_start:part_start + self.MAX_FLUSH_SIZE]
                if not len(buffer_part):
                    # No more data
                    break

                # Upload split buffer in parallel
                start_range = start + part_start
                futures.append(self._workers.submit(
                    self._update_range, data=buffer_part.tobytes(),
                    start_range=start_range,
                    end_range=start_range + len(buffer_part) - 1,
                    **self._client_kwargs))

            with _handle_azure_exception():
                # Wait for upload completion
                for future in _as_completed(futures):
                    future.result()

        else:
            # Buffer lower than limit, do one requests.
            with _handle_azure_exception():
                self._update_range(
                    data=buffer.tobytes(), start_range=start,
                    end_range=end - 1, **self._client_kwargs)


Instruction:
Can you tell what is the following Python 3 function doing
def _generate_async(self, generator):
        first_value_future = self._workers.submit(next, generator)

        def get_first_element(future=first_value_future):
            """
            Get first element value from future.

            Args:
                future (concurrent.futures._base.Future): First value future.

            Returns:
                Evaluated value
            """
            try:
                yield future.result()
            except StopIteration:
                return

        return chain(get_first_element(), generator)

Response:
A generator function that returns the previous generator object after having run the first element evaluated
            in background task.


Instruction:
How would you implement a function in Python 3 that
handles Swift exception and convert to class IO exceptions

Response:
def _handle_client_exception():
    """
    Handle Swift exception and convert to class
    IO exceptions

    Raises:
        OSError subclasses: IO error.
    """
    try:
        yield

    except _ClientException as exception:
        if exception.http_status in _ERROR_CODES:
            raise _ERROR_CODES[exception.http_status](
                exception.http_reason)
        raise


Instruction:
Can you generate the documentation for the following Python 3 function
def copy(self, src, dst, other_system=None):
        container, obj = self.split_locator(src)
        with _handle_client_exception():
            self.client.copy_object(
                container=container, obj=obj, destination=self.relpath(dst))

Response: Copy object of the same storage.


Instruction:
Explain what the following Python 3 code does
def get_client_kwargs(self, path):
        container, obj = self.split_locator(path)
        kwargs = dict(container=container)
        if obj:
            kwargs['obj'] = obj
        return kwargs

Response: Get base keyword arguments for a specific path.


Instruction:
Can you create a Python 3 function that
returns a new instance of the Swift client.

Response:
def _get_client(self):
        """
        Swift client

        Returns:
            swiftclient.client.Connection: client
        """
        kwargs = self._storage_parameters

        # Handles unsecure mode
        if self._unsecure:
            kwargs = kwargs.copy()
            kwargs['ssl_compression'] = False

        return _swift.client.Connection(**kwargs)


Instruction:
Make a summary of the following Python 3 code
def _head(self, client_kwargs):
        with _handle_client_exception():
            # Object
            if 'obj' in client_kwargs:
                return self.client.head_object(**client_kwargs)

            # Container
            return self.client.head_container(**client_kwargs)

Response: Returns object HTTP header.


Instruction:
Given the following Python 3 function, write the documentation
def _make_dir(self, client_kwargs):
        with _handle_client_exception():
            # Object
            if 'obj' in client_kwargs:
                return self.client.put_object(
                    client_kwargs['container'], client_kwargs['obj'], b'')

            # Container
            return self.client.put_container(client_kwargs['container'])

Response:
Make a directory.

        args:
            client_kwargs (dict): Client arguments.


Instruction:
Explain what the following Python 3 code does
def _remove(self, client_kwargs):
        with _handle_client_exception():
            # Object
            if 'obj' in client_kwargs:
                return self.client.delete_object(
                    client_kwargs['container'], client_kwargs['obj'])

            # Container
            return self.client.delete_container(client_kwargs['container'])

Response: Remove an object from the database.


Instruction:
Can you generate the documentation for the following Python 3 function
def _list_locators(self):
        with _handle_client_exception():
            response = self.client.get_account()

        for container in response[1]:
            yield container.pop('name'), container

Response:
Lists locators.

        Returns:
            generator of tuple: locator name str, locator header dict


Instruction:
Make a summary of the following Python 3 code
def _list_objects(self, client_kwargs, path, max_request_entries):
        kwargs = dict(prefix=path)
        if max_request_entries:
            kwargs['limit'] = max_request_entries
        else:
            kwargs['full_listing'] = True

        with _handle_client_exception():
            response = self.client.get_container(
                client_kwargs['container'], **kwargs)

        for obj in response[1]:
            yield obj.pop('name'), obj

Response: List objects in the current locator.


Instruction:
Create a Python 3 function to
read a range of bytes in stream.

Response:
def _read_range(self, start, end=0):
        """
        Read a range of bytes in stream.

        Args:
            start (int): Start stream position.
            end (int): End stream position.
                0 To not specify end.

        Returns:
            bytes: number of bytes read
        """
        try:
            with _handle_client_exception():
                return self._client.get_object(*self._client_args, headers=dict(
                    Range=self._http_range(start, end)))[1]

        except _ClientException as exception:
            if exception.http_status == 416:
                # EOF
                return b''
            raise


Instruction:
Write a Python 3 script for
flushing the write buffers of the stream if applicable.

Response:
def _flush(self, buffer):
        """
        Flush the write buffers of the stream if applicable.

        Args:
            buffer (memoryview): Buffer content.
        """
        container, obj = self._client_args
        with _handle_client_exception():
            self._client.put_object(container, obj, buffer)


Instruction:
Explain what the following Python 3 code does
def _flush(self):
        # Upload segment with workers
        name = self._segment_name % self._seek
        response = self._workers.submit(
            self._client.put_object, self._container, name,
            self._get_buffer())

        # Save segment information in manifest
        self._write_futures.append(dict(
            etag=response, path='/'.join((self._container, name))))

Response: Flush the write buffers of the stream.


Instruction:
Implement a Python 3 function for
closing the object in write mode.

Response:
def _close_writable(self):
        """
        Close the object in write mode.
        """
        # Wait segments upload completion
        for segment in self._write_futures:
            segment['etag'] = segment['etag'].result()

        # Upload manifest file
        with _handle_client_exception():
            self._client.put_object(self._container, self._object_name, _dumps(
                self._write_futures), query_string='multipart-manifest=put')


Instruction:
Implement a function in Python 3 to
initialize file on a mode.

Response:
def _init_append(self):
        """
        Initializes file on 'a' mode.
        """
        # Require to load the full file content in buffer
        self._write_buffer[:] = self._readall()

        # Make initial seek position to current end of file
        self._seek = self._size


Instruction:
Create a Python 3 function for
flushing the write buffers of the object if applicable and close the object.

Response:
def close(self):
        """
        Flush the write buffers of the stream if applicable and
        close the object.
        """
        if self._writable and not self._is_raw_of_buffered and not self._closed:
            self._closed = True
            if self._write_buffer:
                self.flush()


Instruction:
Can you create a Python 3 function that
reads the next size bytes from the stream without advancing the position.

Response:
def _peek(self, size=-1):
        """
        Return bytes from the stream without advancing the position.

        Args:
            size (int): Number of bytes to read. -1 to read the full
                stream.

        Returns:
            bytes: bytes read
        """
        with self._seek_lock:
            seek = self._seek
        with handle_os_exceptions():
            return self._read_range(seek, seek + size)


Instruction:
Can you generate the documentation for the following Python 3 function
def readall(self):
        if not self._readable:
            raise UnsupportedOperation('read')

        with self._seek_lock:
            # Get data starting from seek
            with handle_os_exceptions():
                if self._seek and self._seekable:
                    data = self._read_range(self._seek)

                # Get all data
                else:
                    data = self._readall()

            # Update seek
            self._seek += len(data)
        return data

Response: Read and return all the bytes from the stream until EOF.


Instruction:
Explain what the following Python 3 code does
def readinto(self, b):
        if not self._readable:
            raise UnsupportedOperation('read')

        # Get and update stream positions
        size = len(b)
        with self._seek_lock:
            start = self._seek
            end = start + size
            self._seek = end

        # Read data range
        with handle_os_exceptions():
            read_data = self._read_range(start, end)

        # Copy to bytes-like object
        read_size = len(read_data)
        if read_size:
            memoryview(b)[:read_size] = read_data

        # Update stream position if end of file
        if read_size != size:
            with self._seek_lock:
                self._seek = start + read_size

        # Return read size
        return read_size

Response: Reads bytes into a pre - allocated writable bytes - like object b and returns the number of bytes read.


Instruction:
Explain what the following Python 3 code does
def seek(self, offset, whence=SEEK_SET):
        if not self._seekable:
            raise UnsupportedOperation('seek')

        seek = self._update_seek(offset, whence)

        # If seek move out of file, add padding until new seek position.
        if self._writable:
            size = len(self._write_buffer)
            if seek > size:
                self._write_buffer[seek:size] = b'\0' * (seek - size)

        return seek

Response: Change the stream position to the given byte offset.


Instruction:
Can you tell what is the following Python 3 function doing
def _update_seek(self, offset, whence):
        with self._seek_lock:
            if whence == SEEK_SET:
                self._seek = offset
            elif whence == SEEK_CUR:
                self._seek += offset
            elif whence == SEEK_END:
                self._seek = offset + self._size
            else:
                raise ValueError('whence value %s unsupported' % whence)
        return self._seek

Response:
Update seek value.

        Args:
            offset (int): Offset.
            whence (int): Whence.

        Returns:
            int: Seek position.


Instruction:
Given the following Python 3 function, write the documentation
def write(self, b):
        if not self._writable:
            raise UnsupportedOperation('write')

        # This function write data in a buffer
        # "flush()" need to be called to really write content on
        # Cloud Storage
        size = len(b)
        with self._seek_lock:
            start = self._seek
            end = start + size
            self._seek = end

        buffer = self._write_buffer
        if end <= len(buffer):
            buffer = memoryview(buffer)
        buffer[start:end] = b
        return size

Response: Writes the given bytes - like object b to the underlying raw stream and returns the number of bytes written.


Instruction:
Write a Python 3 script to
check for HTTP errors and raise OSError if relevant.

Response:
def _handle_http_errors(response):
    """
    Check for HTTP errors and raise
    OSError if relevant.

    Args:
        response (requests.Response):

    Returns:
        requests.Response: response
    """
    code = response.status_code
    if 200 <= code < 400:
        return response
    elif code in (403, 404):
        raise {403: _ObjectPermissionError,
               404: _ObjectNotFoundError}[code](response.reason)
    response.raise_for_status()


Instruction:
How would you explain what the following Python 3 function does
def _head(self, client_kwargs):
        return _handle_http_errors(
            self.client.request(
                'HEAD', timeout=self._TIMEOUT, **client_kwargs)).headers

Response: Returns object HTTP header.


Instruction:
Write a Python 3 function for
reading a range of bytes in stream.

Response:
def _read_range(self, start, end=0):
        """
        Read a range of bytes in stream.

        Args:
            start (int): Start stream position.
            end (int): End stream position.
                0 To not specify end.

        Returns:
            bytes: number of bytes read
        """
        # Get object part
        response = self._client.request(
            'GET', self.name, headers=dict(Range=self._http_range(start, end)),
            timeout=self._TIMEOUT)

        if response.status_code == 416:
            # EOF
            return b''

        # Get object content
        return _handle_http_errors(response).content


Instruction:
Explain what the following Python 3 code does
def _readall(self):
        return _handle_http_errors(
            self._client.request(
                'GET', self.name, timeout=self._TIMEOUT)).content

Response: Read and return all the bytes from the stream until EOF.


Instruction:
Create a Python 3 function to
flush the write buffers of the stream if applicable and the object on the cloud is saved.

Response:
def flush(self):
        """
        Flush the write buffers of the stream if applicable and
        save the object on the cloud.
        """
        if self._writable:
            with self._seek_lock:
                buffer = self._get_buffer()

                # Flush that part of the file
                end = self._seek
                start = end - len(buffer)

                # Clear buffer
                self._write_buffer = bytearray()

            # Flush content
            with handle_os_exceptions():
                self._flush(buffer, start, end)


Instruction:
Explain what the following Python 3 code does
def seek(self, offset, whence=SEEK_SET):
        if not self._seekable:
            raise UnsupportedOperation('seek')

        # Flush before moving position
        self.flush()

        return self._update_seek(offset, whence)

Response: Change the stream position to the given byte offset.


Instruction:
Can you write a function in Python 3 where it
flushes the buffer of the stream if applicable.

Response:
def _flush(self):
        """
        Flush the write buffers of the stream if applicable.

        In write mode, send the buffer content to the cloud object.
        """
        # Flush buffer to specified range
        buffer = self._get_buffer()
        start = self._buffer_size * (self._seek - 1)
        end = start + len(buffer)

        future = self._workers.submit(
            self._flush_range, buffer=buffer, start=start, end=end)
        self._write_futures.append(future)
        future.add_done_callback(partial(self._update_size, end))


Instruction:
Can you tell what is the following Python 3 function doing
def _update_size(self, size, future):
        with self._size_lock:
            # Update value
            if size > self._size and future.done:
                # Size can be lower if seek down on an 'a' mode open file.
                self._size = size

Response: Update the size of the current entry in the cache.


Instruction:
Write a Python 3 function that can
flush a buffer to a range of the file.

Response:
def _flush_range(self, buffer, start, end):
        """
        Flush a buffer to a range of the file.

        Meant to be used asynchronously, used to provides parallel flushing of
        file parts when applicable.

        Args:
            buffer (memoryview): Buffer content.
            start (int): Start of buffer position to flush.
            end (int): End of buffer position to flush.
        """
        # On first call, Get file size if exists
        with self._size_lock:
            if not self._size_synched:
                self._size_synched = True
                try:
                    self._size = self.raw._size
                except (ObjectNotFoundError, UnsupportedOperation):
                    self._size = 0

        # It is not possible to flush a part if start > size:
        # If it is the case, wait that previous parts are flushed before
        # flushing this one
        while start > self._size:
            sleep(self._FLUSH_WAIT)

        # Flush buffer using RAW IO
        self._raw_flush(buffer, start, end)


Instruction:
Write a Python 3 script to
execute a shell command.

Response:
def run(cmd):
    """ Execute a shell command.

    Both envoy and python-sh failed me...
    commands, although deprecated, feels like the easiest tool to use.
    """

    status, output = commands.getstatusoutput(cmd)
    if status:
        print(output)
    return status == 0


Instruction:
Write a Python 3 script to
read in all datanommer entries from a file created with datanommer - dump > myfile. json

Response:
def read_datanommer_entries_from_filedump():
    """ Read in all datanommer entries from a file created with:

      $ datanommer-dump > myfile.json
    """

    # TODO -- un-hardcode this filename when I need to run this next time.
    #filename = "../myfile.json"
    filename = "../datanommer-dump-2012-11-22.json"
    print("Reading %s" % filename)
    progress = progressbar.ProgressBar(widgets=[
        progressbar.widgets.Percentage(),
        progressbar.widgets.Bar(),
        progressbar.widgets.ETA(),
    ])

    def _entries():
        failed = 0
        with open(filename, 'r') as f:
            raw = f.read()
            lines = raw.split('\n}\n')
            for line in progress(lines):
                try:
                    yield json.loads(line + "\n}")
                except:
                    failed += 1
        print(" * Failed to parse %i json objects" % failed)

    def comp(a, b):
        return cmp(a['timestamp'], b['timestamp'])

    result = sorted(list(_entries()), cmp=comp)
    print(" * Read and sorted %i messages" % len(result))
    print()
    return result


Instruction:
Can you write a function in Python 3 where it
creates or update a model instance.

Response:
def create_or_update(self,
                         identifier: Identifier,
                         data: Dict[str, Any],
                         ) -> Tuple[object, bool]:
        """
        Create or update a model.

        :param identifier: An object with :attr:`class_name` and :attr:`key`
                           attributes
        :param data: A dictionary keyed by column name, with values being the
                     converted values to set on the model instance
        :return: A two-tuple of model instance and whether or not it was created.
        """
        raise NotImplementedError


Instruction:
How would you implement a function in Python 3 that
returns a dictionary of raw values for a specific identifier and data.

Response:
def maybe_convert_values(self,
                             identifier: Identifier,
                             data: Dict[str, Any],
                             ) -> Dict[str, Any]:
        """
        Takes a dictionary of raw values for a specific identifier, as parsed
        from the YAML file, and depending upon the type of db column the data
        is meant for, decides what to do with the value (eg leave it alone,
        convert a string to a date/time instance, or convert identifiers to
        model instances by calling :meth:`self.loader.convert_identifiers`)

        :param identifier: An object with :attr:`class_name` and :attr:`key`
                           attributes
        :param data: A dictionary keyed by column name, with values being the
                     raw values as parsed from the YAML
        :return: A dictionary keyed by column name, with values being the
                 converted values meant to be set on the model instance
        """
        raise NotImplementedError


Instruction:
Write a Python 3 script to
copy a file from src to dst.

Response:
def copy(self, src, dst, other_system=None):
        """
        Copy object of the same storage.

        Args:
            src (str): Path or URL.
            dst (str): Path or URL.
            other_system (pycosio.storage.azure._AzureBaseSystem subclass):
                The source storage system.
        """
        with _handle_azure_exception():
            self.client.copy_file(
                copy_source=(other_system or self)._format_src_url(src, self),
                **self.get_client_kwargs(dst))


Instruction:
Write a Python 3 script to
get base keyword arguments for a specific path.

Response:
def get_client_kwargs(self, path):
        """
        Get base keyword arguments for client for a
        specific path.

        Args:
            path (str): Absolute path or URL.

        Returns:
            dict: client args
        """
        # Remove query string from URL
        path = path.split('?', 1)[0]

        share_name, relpath = self.split_locator(path)
        kwargs = dict(share_name=share_name)

        # Directory
        if relpath and relpath[-1] == '/':
            kwargs['directory_name'] = relpath.rstrip('/')

        # File
        elif relpath:
            try:
                kwargs['directory_name'], kwargs['file_name'] = relpath.rsplit(
                    '/', 1)
            except ValueError:
                kwargs['directory_name'] = ''
                kwargs['file_name'] = relpath

        # Else, Share only
        return kwargs


Instruction:
Can you create a Python 3 function that
returns object or bucket HTTP header.

Response:
def _head(self, client_kwargs):
        """
        Returns object or bucket HTTP header.

        Args:
            client_kwargs (dict): Client arguments.

        Returns:
            dict: HTTP header.
        """
        with _handle_azure_exception():
            # File
            if 'file_name' in client_kwargs:
                result = self.client.get_file_properties(**client_kwargs)

            # Directory
            elif 'directory_name' in client_kwargs:
                result = self.client.get_directory_properties(**client_kwargs)

            # Share
            else:
                result = self.client.get_share_properties(**client_kwargs)

        return self._model_to_dict(result)


Instruction:
Implement a function in Python 3 to
list locators. Returns: generator of tuple: locator name str, locator header dict

Response:
def _list_locators(self):
        """
        Lists locators.

        Returns:
            generator of tuple: locator name str, locator header dict
        """
        with _handle_azure_exception():
            for share in self.client.list_shares():
                yield share.name, self._model_to_dict(share)


Instruction:
Can you generate the documentation for the following Python 3 function
def _list_objects(self, client_kwargs, max_request_entries):
        client_kwargs = self._update_listing_client_kwargs(
            client_kwargs, max_request_entries)

        with _handle_azure_exception():
            for obj in self.client.list_directories_and_files(**client_kwargs):
                yield (obj.name, self._model_to_dict(obj),
                       isinstance(obj, _Directory))

Response: A generator that yields objects from the Cloud Storage API.


Instruction:
Make a summary of the following Python 3 code
def _make_dir(self, client_kwargs):
        with _handle_azure_exception():
            # Directory
            if 'directory_name' in client_kwargs:
                return self.client.create_directory(
                    share_name=client_kwargs['share_name'],
                    directory_name=client_kwargs['directory_name'])

            # Share
            return self.client.create_share(**client_kwargs)

Response: Make a directory and a share.


Instruction:
Given the following Python 3 function, write the documentation
def _remove(self, client_kwargs):
        with _handle_azure_exception():
            # File
            if 'file_name' in client_kwargs:
                return self.client.delete_file(
                    share_name=client_kwargs['share_name'],
                    directory_name=client_kwargs['directory_name'],
                    file_name=client_kwargs['file_name'])

            # Directory
            elif 'directory_name' in client_kwargs:
                return self.client.delete_directory(
                    share_name=client_kwargs['share_name'],
                    directory_name=client_kwargs['directory_name'])

            # Share
            return self.client.delete_share(
                share_name=client_kwargs['share_name'])

Response: Remove an object from the Cloud Storage.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _update_range(self, data, **kwargs):
        self._client.update_range(data=data, **kwargs)

Response: Update the range of the data.


Instruction:
Here you have a function in Python 3, explain what it does
def handle_bodhi(msg):

    if 'bodhi.update.comment' in msg.topic:
        username = msg.msg['comment']['author']
    elif 'bodhi.buildroot_override' in msg.topic:
        username = msg.msg['override']['submitter']
    else:
        username = msg.msg.get('update', {}).get('submitter')
    return username

Response: Given a bodhi message return the FAS username.


Instruction:
Explain what the following Python 3 code does
def handle_wiki(msg):

    if 'wiki.article.edit' in msg.topic:
        username = msg.msg['user']
    elif 'wiki.upload.complete' in msg.topic:
        username = msg.msg['user_text']
    else:
        raise ValueError("Unhandled topic.")

    return username

Response: Given a wiki message return the FAS username.


Instruction:
Write a Python 3 script to
check if file is a local file or a storage file.

Response:
def is_storage(url, storage=None):
    """
    Check if file is a local file or a storage file.

    File is considered local if:
        - URL is a local path.
        - URL starts by "file://"
        - a "storage" is provided.

    Args:
        url (str): file path or URL
        storage (str): Storage name.

    Returns:
        bool: return True if file is local.
    """
    if storage:
        return True
    split_url = url.split('://', 1)
    if len(split_url) == 2 and split_url[0].lower() != 'file':
        return True
    return False


Instruction:
How would you implement a function in Python 3 that
checks if path is storage and format it.

Response:
def format_and_is_storage(path):
    """
    Checks if path is storage and format it.

    If path is an opened file-like object, returns is storage as True.

    Args:
        path (path-like object or file-like object):

    Returns:
        tuple: str or file-like object (Updated path),
            bool (True if is storage).
    """
    if not hasattr(path, 'read'):
        path = fsdecode(path).replace('\\', '/')
        return path, is_storage(path)
    return path, True


Instruction:
Implement a function in Python 3 to
decorate a cloud object compatible function to provides fall back to standard function if used on local files. Args: std_function (function): standard function to used with local files. Returns: function: new function

Response:
def equivalent_to(std_function):
    """
    Decorates a cloud object compatible function
    to provides fall back to standard function if
    used on local files.

    Args:
        std_function (function): standard function to
            used with local files.

    Returns:
        function: new function
    """

    def decorate(cos_function):
        """Decorator argument handler"""

        @wraps(cos_function)
        def decorated(path, *args, **kwargs):
            """Decorated function"""

            # Handles path-like objects
            path = fsdecode(path).replace('\\', '/')

            # Storage object: Handle with Cloud object storage
            # function
            if is_storage(path):
                with handle_os_exceptions():
                    return cos_function(path, *args, **kwargs)

            # Local file: Redirect to standard function
            return std_function(path, *args, **kwargs)

        return decorated

    return decorate


Instruction:
Given the following Python 3 function, write the documentation
def _handle_oss_error():
    try:
        yield

    except _OssError as exception:
        if exception.status in _ERROR_CODES:
            raise _ERROR_CODES[exception.status](
                exception.details.get('Message', ''))
        raise

Response: Handle OSS exceptions and convert to class IO exceptions


Instruction:
Can you tell what is the following Python 3 function doing
def copy(self, src, dst, other_system=None):
        copy_source = self.get_client_kwargs(src)
        copy_destination = self.get_client_kwargs(dst)
        with _handle_oss_error():
            bucket = self._get_bucket(copy_destination)
            bucket.copy_object(
                source_bucket_name=copy_source['bucket_name'],
                source_key=copy_source['key'],
                target_key=copy_destination['key'])

Response: Copy object of the same storage.


Instruction:
Given the following Python 3 function, write the documentation
def _get_client(self):
        return (_oss.StsAuth if 'security_token' in self._storage_parameters
                else _oss.Auth if self._storage_parameters
                else _oss.AnonymousAuth)(**self._storage_parameters)

Response: Returns the client object for the current session.


Instruction:
Can you implement a function in Python 3 that
returns the URL roots for this storage.

Response:
def _get_roots(self):
        """
        Return URL roots for this storage.

        Returns:
            tuple of str or re.Pattern: URL roots
        """

        return (
            # OSS Scheme
            # - oss://<bucket>/<key>
            'oss://',

            # URL (With common aliyuncs.com endpoint):
            # - http://<bucket>.oss-<region>.aliyuncs.com/<key>
            # - https://<bucket>.oss-<region>.aliyuncs.com/<key>

            # Note: "oss-<region>.aliyuncs.com" may be replaced by another
            # endpoint

            _re.compile((r'https?://[\w-]+.%s' % self._endpoint.split(
                '//', 1)[1]).replace('.', r'\.')))


Instruction:
Can you generate the documentation for the following Python 3 function
def _get_bucket(self, client_kwargs):
        return _oss.Bucket(self.client, endpoint=self._endpoint,
                           bucket_name=client_kwargs['bucket_name'])

Response: Get the object in the appropriate bucket.


Instruction:
Can you create a Python 3 function that
returns True if object is a symbolic link.

Response:
def islink(self, path=None, header=None):
        """
        Returns True if object is a symbolic link.

        Args:
            path (str): File path or URL.
            header (dict): Object header.

        Returns:
            bool: True if object is Symlink.
        """
        if header is None:
            header = self._head(self.get_client_kwargs(path))

        for key in ('x-oss-object-type', 'type'):
            try:
                return header.pop(key) == 'Symlink'
            except KeyError:
                continue
        return False


Instruction:
How would you code a function in Python 3 to
return object HTTP header.

Response:
def _head(self, client_kwargs):
        """
        Returns object HTTP header.

        Args:
            client_kwargs (dict): Client arguments.

        Returns:
            dict: HTTP header.
        """
        with _handle_oss_error():
            bucket = self._get_bucket(client_kwargs)

            # Object
            if 'key' in client_kwargs:
                return bucket.head_object(
                    key=client_kwargs['key']).headers

            # Bucket
            return bucket.get_bucket_info().headers


Instruction:
Write a Python 3 script for
making a directory. args: client_kwargs (dict): Client arguments.

Response:
def _make_dir(self, client_kwargs):
        """
        Make a directory.

        args:
            client_kwargs (dict): Client arguments.
        """
        with _handle_oss_error():
            bucket = self._get_bucket(client_kwargs)

            # Object
            if 'key' in client_kwargs:
                return bucket.put_object(
                    key=client_kwargs['key'], data=b'')

            # Bucket
            return bucket.create_bucket()


Instruction:
How would you implement a function in Python 3 that
removes an object from the cache.

Response:
def _remove(self, client_kwargs):
        """
        Remove an object.

        args:
            client_kwargs (dict): Client arguments.
        """
        with _handle_oss_error():
            bucket = self._get_bucket(client_kwargs)

            # Object
            if 'key' in client_kwargs:
                return bucket.delete_object(key=client_kwargs['key'])

            # Bucket
            return bucket.delete_bucket()


Instruction:
Create a Python 3 function to
convert OSS model to dict.

Response:
def _model_to_dict(model, ignore):
        """
        Convert OSS model to dict.

        Args:
            model (oss2.models.RequestResult): Model.
            ignore (tuple of str): Keys to not insert to dict.

        Returns:
            dict: Model dict version.
        """
        return {attr: value for attr, value in model.__dict__.items()
                if not attr.startswith('_') and attr not in ignore}


Instruction:
Explain what the following Python 3 code does
def _list_locators(self):
        with _handle_oss_error():
            response = _oss.Service(
                self.client, endpoint=self._endpoint).list_buckets()

        for bucket in response.buckets:
            yield bucket.name, self._model_to_dict(bucket, ('name',))

Response:
Lists locators.

        Returns:
            generator of tuple: locator name str, locator header dict


Instruction:
Can you generate the documentation for the following Python 3 function
def _list_objects(self, client_kwargs, path, max_request_entries):
        kwargs = dict()
        if max_request_entries:
            kwargs['max_keys'] = max_request_entries

        bucket = self._get_bucket(client_kwargs)

        while True:
            with _handle_oss_error():
                response = bucket.list_objects(prefix=path, **kwargs)

            if not response.object_list:
                # In case of empty dir, return empty dir path:
                # if empty result, the dir do not exists.
                raise _ObjectNotFoundError('Not found: %s' % path)

            for obj in response.object_list:
                yield obj.key, self._model_to_dict(obj, ('key',))

            # Handles results on more than one page
            if response.next_marker:
                client_kwargs['marker'] = response.next_marker
            else:
                # End of results
                break

Response: A generator function that returns objects from the specified path.


Instruction:
Can you generate the documentation for the following Python 3 function
def _read_range(self, start, end=0):
        if start >= self._size:
            # EOF. Do not detect using 416 (Out of range) error, 200 returned.
            return bytes()

        # Get object bytes range
        with _handle_oss_error():
            response = self._bucket.get_object(key=self._key, headers=dict(
                Range=self._http_range(
                    # Returns full file if end > size
                    start, end if end <= self._size else self._size)))

        # Get object content
        return response.read()

Response: Read a range of bytes in stream.


Instruction:
Make a summary of the following Python 3 code
def _readall(self):
        with _handle_oss_error():
            return self._bucket.get_object(key=self._key).read()

Response: Read and return all the bytes from the stream until EOF.


Instruction:
Implement a Python 3 function for
flushing the write buffers of the stream if applicable.

Response:
def _flush(self, buffer):
        """
        Flush the write buffers of the stream if applicable.

        Args:
            buffer (memoryview): Buffer content.
        """
        with _handle_oss_error():
            self._bucket.put_object(key=self._key, data=buffer.tobytes())


Instruction:
Write a Python 3 script for
flushing the write buffers of the stream.

Response:
def _flush(self):
        """
        Flush the write buffers of the stream.
        """
        # Initialize multipart upload
        if self._upload_id is None:
            with _handle_oss_error():
                self._upload_id = self._bucket.init_multipart_upload(
                    self._key).upload_id

        # Upload part with workers
        response = self._workers.submit(
            self._bucket.upload_part, key=self._key, upload_id=self._upload_id,
            part_number=self._seek, data=self._get_buffer().tobytes())

        # Save part information
        self._write_futures.append(
            dict(response=response, part_number=self._seek))


Instruction:
Explain what the following Python 3 code does
def _close_writable(self):
        # Wait parts upload completion
        parts = [_PartInfo(part_number=future['part_number'],
                           etag=future['response'].result().etag)
                 for future in self._write_futures]

        # Complete multipart upload
        with _handle_oss_error():
            try:
                self._bucket.complete_multipart_upload(
                    key=self._key, upload_id=self._upload_id, parts=parts)
            except _OssError:
                # Clean up failed upload
                self._bucket.abort_multipart_upload(
                    key=self._key, upload_id=self._upload_id)
                raise

Response: Close the object in write mode.


Instruction:
Write a Python 3 function for
functioning that opens a file and returns a corresponding file - like object.

Response:
def cos_open(file, mode='r', buffering=-1, encoding=None, errors=None,
             newline=None, storage=None, storage_parameters=None, unsecure=None,
             **kwargs):
    """
    Open file and return a corresponding file object.

    Equivalent to "io.open" or builtin "open".

    File can also be binary opened file-like object.

    Args:
        file (path-like object or file-like object): File path, object URL or
            opened file-like object.
        mode (str): mode in which the file is opened (default to 'rb').
            see "io.open" for all possible modes. Note that all modes may
            not be supported by all kind of file and storage.
        buffering (int): Set the buffering policy.
            -1 to use default behavior,
            0 to switch buffering off,
            1 to select line buffering (only usable in text mode),
            and an integer > 1 to indicate the size in bytes of a
            fixed-size chunk buffer.
            See "io.open" for more information.
        encoding (str): The name of the encoding used to
            decode or encode the file. This should only be used in text mode.
            See "io.open" for more information.
        errors (str):  Specifies how encoding and decoding errors
            are to be handled.
            This should only be used in text mode.
            See "io.open" for more information.
        newline (str): Controls how universal newlines mode works.
            This should only be used in text mode.
            See "io.open" for more information.
        storage (str): Storage name.
        storage_parameters (dict): Storage configuration parameters.
            Generally, client configuration and credentials.
        unsecure (bool): If True, disables TLS/SSL to improves
            transfer performance. But makes connection unsecure.
            Default to False.
        kwargs: Other arguments to pass to opened object.
            Note that theses arguments may not be compatible with
            all kind of file and storage.

    Returns:
        file-like object: opened file.

    Raises:
        OSError: If the file cannot be opened.
        FileExistsError: File open in 'x' mode already exists.
    """
    # Handles file-like objects:
    if hasattr(file, 'read'):
        with _text_io_wrapper(file, mode, encoding, errors, newline) as wrapped:
            yield wrapped
        return

    # Handles path-like objects
    file = fsdecode(file).replace('\\', '/')

    # Storage object
    if is_storage(file, storage):
        with get_instance(
                name=file, cls='raw' if buffering == 0 else 'buffered',
                storage=storage, storage_parameters=storage_parameters,
                mode=mode, unsecure=unsecure, **kwargs) as stream:
            with _text_io_wrapper(stream, mode=mode, encoding=encoding,
                                  errors=errors, newline=newline) as wrapped:
                yield wrapped

    # Local file: Redirect to "io.open"
    else:
        with io_open(file, mode, buffering, encoding, errors, newline,
                     **kwargs) as stream:
            yield stream


Instruction:
Write a Python 3 script to
wrap a binary stream to a Text stream.

Response:
def _text_io_wrapper(stream, mode, encoding, errors, newline):
    """Wrap a binary stream to Text stream.

    Args:
        stream (file-like object): binary stream.
        mode (str): Open mode.
        encoding (str): Stream encoding.
        errors (str): Decoding error handling.
        newline (str): Universal newlines
    """
    # Text mode, if not already a text stream
    # That has the "encoding" attribute
    if "t" in mode and not hasattr(stream, 'encoding'):
        text_stream = TextIOWrapper(
            stream, encoding=encoding, errors=errors, newline=newline)
        yield text_stream
        text_stream.flush()

    # Binary mode (Or already text stream)
    else:
        yield stream


Instruction:
Can you generate a brief explanation for the following Python 3 code
def random_model(ctx, model_class_name):
    model_identifiers = ctx['model_identifiers'][model_class_name]
    if not model_identifiers:
        return 'None'
    idx = random.randrange(0, len(model_identifiers))
    return '"%s(%s)"' % (model_class_name, model_identifiers[idx])

Response: Returns a random model identifier by class name.


Instruction:
Write a Python 3 function for
returning a random model identifier by class name.

Response:
def random_models(ctx, model_class_name, min_count=0, max_count=3):
    """
    Get a random model identifier by class name. Example usage::

        # db/fixtures/Tag.yml
        {% for i in range(0, 10) %}
        tag{{ i }}:
            name: {{ faker.name() }}
        {% endfor %}

        # db/fixtures/Post.yml
        a_blog_post:
            tags: {{ random_models('Tag') }}

    Will render to something like the following::

        # db/fixtures/Post.yml (rendered)
        a blog_post:
            tags: ["Tag(tag2, tag5)"]

    :param ctx: The context variables of the current template (passed automatically)
    :param model_class_name: The class name of the models to get.
    :param min_count: The minimum number of models to return.
    :param max_count: The maximum number of models to return.
    """
    model_identifiers = ctx['model_identifiers'][model_class_name]
    num_models = random.randint(min_count, min(max_count, len(model_identifiers)))
    if num_models == 0:
        return '[]'

    added = set()
    while len(added) < num_models:
        idx = random.randrange(0, len(model_identifiers))
        added.add(model_identifiers[idx])
    return '["%s(%s)"]' % (model_class_name, ','.join(added))


Instruction:
How would you code a function in Python 3 to
list objects. Args: path (str): Path or URL. relative (bool): Path is relative to current root. first_level (bool): It True, returns only first level objects. Else, returns full tree. max_request_entries (int): If specified, maximum entries returned by request. Returns: generator of tuple: object name str, object header dict

Response:
def list_objects(self, path='', relative=False, first_level=False,
                     max_request_entries=None):
        """
        List objects.

        Args:
            path (str): Path or URL.
            relative (bool): Path is relative to current root.
            first_level (bool): It True, returns only first level objects.
                Else, returns full tree.
            max_request_entries (int): If specified, maximum entries returned
                by request.

        Returns:
            generator of tuple: object name str, object header dict
        """
        entries = 0
        next_values = []
        max_request_entries_arg = None

        if not relative:
            path = self.relpath(path)

        # From root
        if not path:
            objects = self._list_locators()

        # Sub directory
        else:
            objects = self._list_objects(
                self.get_client_kwargs(path), max_request_entries)

        # Yield file hierarchy
        for obj in objects:
            # Generate first level objects entries
            try:
                name, header, is_directory = obj
            except ValueError:
                # Locators
                name, header = obj
                is_directory = True

            # Start to generate subdirectories content
            if is_directory and not first_level:
                name = next_path = name.rstrip('/') + '/'

                if path:
                    next_path = '/'.join((path.rstrip('/'), name))

                if max_request_entries is not None:
                    max_request_entries_arg = max_request_entries - entries

                next_values.append((
                    name, self._generate_async(self.list_objects(
                        next_path, relative=True,
                        max_request_entries=max_request_entries_arg))))

            entries += 1
            yield name, header
            if entries == max_request_entries:
                return

        for next_name, generator in next_values:
            # Generate other levels objects entries
            for name, header in generator:

                entries += 1
                yield '/'.join((next_name.rstrip('/'), name)), header
                if entries == max_request_entries:
                    return


Instruction:
Can you implement a function in Python 3 that
hashes all keys in a timerange to the same value.

Response:
def hash_key(self, key):
        """ "Hash" all keys in a timerange to the same value. """
        for i, destination_key in enumerate(self._dict):
            if key < destination_key:
                return destination_key

        return key


Instruction:
Can you tell what is the following Python 3 function doing
def create_all(self, progress_callback: Optional[callable] = None) -> Dict[str, object]:
        if not self._loaded:
            self._load_data()

        # build up a directed acyclic graph to determine the model instantiation order
        dag = nx.DiGraph()
        for model_class_name, dependencies in self.relationships.items():
            dag.add_node(model_class_name)
            for dep in dependencies:
                dag.add_edge(model_class_name, dep)

        try:
            creation_order = reversed(list(nx.topological_sort(dag)))
        except nx.NetworkXUnfeasible:
            raise Exception('Circular dependency detected between models: '
                            ', '.join(['{a} -> {b}'.format(a=a, b=b)
                                       for a, b in nx.find_cycle(dag)]))

        # create or update the models in the determined order
        rv = {}
        for model_class_name in creation_order:
            for identifier_key, data in self.model_fixtures[model_class_name].items():
                identifier = Identifier(model_class_name, identifier_key)
                data = self.factory.maybe_convert_values(identifier, data)
                self._cache[identifier_key] = data

                model_instance, created = self.factory.create_or_update(identifier, data)
                if progress_callback:
                    progress_callback(identifier, model_instance, created)
                rv[identifier_key] = model_instance

        self.factory.commit()
        return rv

Response: Creates all the models in the fixture files in the fixtures_dir.


Instruction:
Write a Python 3 script to
convert an individual : class : Identifier to a list of model instances or a list of model instances.

Response:
def convert_identifiers(self, identifiers: Union[Identifier, List[Identifier]]):
        """
        Convert an individual :class:`Identifier` to a model instance,
        or a list of Identifiers to a list of model instances.
        """
        if not identifiers:
            return identifiers

        def _create_or_update(identifier):
            data = self._cache[identifier.key]
            return self.factory.create_or_update(identifier, data)[0]

        if isinstance(identifiers, Identifier):
            return _create_or_update(identifiers)
        elif isinstance(identifiers, list) and isinstance(identifiers[0], Identifier):
            return [_create_or_update(identifier) for identifier in identifiers]
        else:
            raise TypeError('`identifiers` must be an Identifier or list of Identifiers.')


Instruction:
How would you code a function in Python 3 to
load all fixtures from given directories and store them in the self. _cache.

Response:
def _load_data(self):
        """
        Load all fixtures from :attr:`fixtures_dir`
        """
        filenames = []
        model_identifiers = defaultdict(list)

        # attempt to load fixture files from given directories (first pass)
        # for each valid model fixture file, read it into the cache and get the
        # list of identifier keys from it
        for fixtures_dir in self.fixture_dirs:
            for filename in os.listdir(fixtures_dir):
                path = os.path.join(fixtures_dir, filename)
                file_ext = filename[filename.find('.')+1:]

                # make sure it's a valid fixture file
                if os.path.isfile(path) and file_ext in {'yml', 'yaml'}:
                    filenames.append(filename)
                    with open(path) as f:
                        self._cache[filename] = f.read()

                    # preload to determine identifier keys
                    with self._preloading_env() as env:
                        rendered_yaml = env.get_template(filename).render()
                        data = yaml.load(rendered_yaml)
                        if data:
                            class_name = filename[:filename.rfind('.')]
                            model_identifiers[class_name] = list(data.keys())

        # second pass where we can render the jinja templates with knowledge of all
        # the model identifier keys (allows random_model and random_models to work)
        for filename in filenames:
            self._load_from_yaml(filename, model_identifiers)

        self._loaded = True


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _load_from_yaml(self, filename: str, model_identifiers: Dict[str, List[str]]):
        class_name = filename[:filename.rfind('.')]
        rendered_yaml = self.env.get_template(filename).render(
            model_identifiers=model_identifiers)
        fixture_data, self.relationships[class_name] = self._post_process_yaml_data(
            yaml.load(rendered_yaml),
            self.factory.get_relationships(class_name))

        for identifier_key, data in fixture_data.items():
            self.model_fixtures[class_name][identifier_key] = data

Response: Load fixtures from the given yaml file.


Instruction:
Implement a Python 3 function for
converting and normalize identifier strings to Identifiers and determine the class relationships.

Response:
def _post_process_yaml_data(self,
                                fixture_data: Dict[str, Dict[str, Any]],
                                relationship_columns: Set[str],
                                ) -> Tuple[Dict[str, Dict[str, Any]], List[str]]:
        """
        Convert and normalize identifier strings to Identifiers, as well as determine
        class relationships.
        """
        rv = {}
        relationships = set()
        if not fixture_data:
            return rv, relationships

        for identifier_id, data in fixture_data.items():
            new_data = {}
            for col_name, value in data.items():
                if col_name not in relationship_columns:
                    new_data[col_name] = value
                    continue

                identifiers = normalize_identifiers(value)
                if identifiers:
                    relationships.add(identifiers[0].class_name)

                if isinstance(value, str) and len(identifiers) <= 1:
                    new_data[col_name] = identifiers[0] if identifiers else None
                else:
                    new_data[col_name] = identifiers

            rv[identifier_id] = new_data
        return rv, list(relationships)


Instruction:
Can you implement a function in Python 3 that
makes sure the jinja environment is minimally configured.

Response:
def _ensure_env(self, env: Union[jinja2.Environment, None]):
        """
        Make sure the jinja environment is minimally configured.
        """
        if not env:
            env = jinja2.Environment()
        if not env.loader:
            env.loader = jinja2.FunctionLoader(lambda filename: self._cache[filename])
        if 'faker' not in env.globals:
            faker = Faker()
            faker.seed(1234)
            env.globals['faker'] = faker
        if 'random_model' not in env.globals:
            env.globals['random_model'] = jinja2.contextfunction(random_model)
        if 'random_models' not in env.globals:
            env.globals['random_models'] = jinja2.contextfunction(random_models)
        return env


Instruction:
Can you generate the documentation for the following Python 3 function
def _preloading_env(self):
        ctx = self.env.globals
        try:
            ctx['random_model'] = lambda *a, **kw: None
            ctx['random_models'] = lambda *a, **kw: None
            yield self.env
        finally:
            ctx['random_model'] = jinja2.contextfunction(random_model)
            ctx['random_models'] = jinja2.contextfunction(random_models)

Response: A context manager that preloads the environment variables for the object.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def get_instance(name, cls='system', storage=None, storage_parameters=None,
                 unsecure=None, *args, **kwargs):
    """
    Get a cloud object storage instance.

    Args:
        name (str): File name, path or URL.
        cls (str): Type of class to instantiate.
            'raw', 'buffered' or 'system'.
        storage (str): Storage name.
        storage_parameters (dict): Storage configuration parameters.
            Generally, client configuration and credentials.
        unsecure (bool): If True, disables TLS/SSL to improves
            transfer performance. But makes connection unsecure.
            Default to False.
        args, kwargs: Instance arguments

    Returns:
        pycosio._core.io_base.ObjectIOBase subclass: Instance
    """
    system_parameters = _system_parameters(
        unsecure=unsecure, storage_parameters=storage_parameters)

    # Gets storage information
    with _MOUNT_LOCK:
        for root in MOUNTED:
            if ((isinstance(root, Pattern) and root.match(name)) or
                    (not isinstance(root, Pattern) and
                     name.startswith(root))):
                info = MOUNTED[root]

                # Get stored storage parameters
                stored_parameters = info.get('system_parameters') or dict()
                if not system_parameters:
                    same_parameters = True
                    system_parameters = stored_parameters
                elif system_parameters == stored_parameters:
                    same_parameters = True
                else:
                    same_parameters = False
                    # Copy not specified parameters from default
                    system_parameters.update({
                        key: value for key, value in stored_parameters.items()
                        if key not in system_parameters})
                break

        # If not found, tries to mount before getting
        else:
            mount_info = mount(
                storage=storage, name=name, **system_parameters)
            info = mount_info[tuple(mount_info)[0]]
            same_parameters = True

    # Returns system class
    if cls == 'system':
        if same_parameters:
            return info['system_cached']
        else:
            return info['system'](
                roots=info['roots'], **system_parameters)

    # Returns other classes
    if same_parameters:
        if 'storage_parameters' not in system_parameters:
            system_parameters['storage_parameters'] = dict()
        system_parameters['storage_parameters'][
            'pycosio.system_cached'] = info['system_cached']

    kwargs.update(system_parameters)
    return info[cls](name=name, *args, **kwargs)

Response: Get a cloud object storage instance.


Instruction:
Write a Python 3 script for
mounting a new storage at a new location.

Response:
def mount(storage=None, name='', storage_parameters=None,
          unsecure=None, extra_root=None):
    """
    Mount a new storage.

    Args:
        storage (str): Storage name.
        name (str): File URL. If storage is not specified,
            URL scheme will be used as storage value.
        storage_parameters (dict): Storage configuration parameters.
            Generally, client configuration and credentials.
        unsecure (bool): If True, disables TLS/SSL to improves
            transfer performance. But makes connection unsecure.
            Default to False.
        extra_root (str): Extra root that can be used in
            replacement of root in path. This can be used to
            provides support for shorter URLS.
            Example: with root "https://www.mycloud.com/user"
            and extra_root "mycloud://" it is possible to access object
            using "mycloud://container/object" instead of
            "https://www.mycloud.com/user/container/object".

    Returns:
        dict: keys are mounted storage, values are dicts of storage information.
    """
    # Tries to infer storage from name
    if storage is None:
        if '://' in name:
            storage = name.split('://', 1)[0].lower()
            # Alias HTTPS to HTTP
            storage = 'http' if storage == 'https' else storage
        else:
            raise ValueError(
                'No storage specified and unable to infer it from file name.')

    # Saves get_storage_parameters
    system_parameters = _system_parameters(
        unsecure=unsecure, storage_parameters=storage_parameters)
    storage_info = dict(storage=storage, system_parameters=system_parameters)

    # Finds module containing target subclass
    for package in STORAGE_PACKAGE:
        try:
            module = import_module('%s.%s' % (package, storage))
            break
        except ImportError:
            continue
    else:
        raise ImportError('No storage named "%s" found' % storage)

    # Case module is a mount redirection to mount multiple storage at once
    if hasattr(module, 'MOUNT_REDIRECT'):
        if extra_root:
            raise ValueError(
                ("Can't define extra_root with %s. "
                 "%s can't have a common root.") % (
                    storage, ', '.join(extra_root)))
        result = dict()
        for storage in getattr(module, 'MOUNT_REDIRECT'):
            result[storage] = mount(
                storage=storage, storage_parameters=storage_parameters,
                unsecure=unsecure)
        return result

    # Finds storage subclass
    classes_items = tuple(_BASE_CLASSES.items())
    for member_name in dir(module):
        member = getattr(module, member_name)
        for cls_name, cls in classes_items:

            # Skip if not subclass of the target class
            try:
                if not issubclass(member, cls) or member is cls:
                    continue
            except TypeError:
                continue

            # The class may have been flag as default or not-default
            default_flag = '_%s__DEFAULT_CLASS' % member.__name__.strip('_')
            try:
                is_default = getattr(member, default_flag)
            except AttributeError:
                is_default = None

            # Skip if explicitly flagged as non default
            if is_default is False:
                continue

            # Skip if is an abstract class not explicitly flagged as default
            elif is_default is not True and member.__abstractmethods__:
                continue

            # Is the default class
            storage_info[cls_name] = member
            break

    # Caches a system instance
    storage_info['system_cached'] = storage_info['system'](**system_parameters)

    # Gets roots
    roots = storage_info['system_cached'].roots

    # Adds extra root
    if extra_root:
        roots = list(roots)
        roots.append(extra_root)
        roots = tuple(roots)
    storage_info['system_cached'].roots = storage_info['roots'] = roots

    # Mounts
    with _MOUNT_LOCK:
        for root in roots:
            MOUNTED[root] = storage_info

        # Reorder to have correct lookup
        items = OrderedDict(
            (key, MOUNTED[key]) for key in reversed(
                sorted(MOUNTED, key=_compare_root)))
        MOUNTED.clear()
        MOUNTED.update(items)

    return {storage: storage_info}


Instruction:
Write a Python 3 function that can
return system keyword arguments removing Nones.

Response:
def _system_parameters(**kwargs):
    """
    Returns system keyword arguments removing Nones.

    Args:
        kwargs: system keyword arguments.

    Returns:
        dict: system keyword arguments.
    """
    return {key: value for key, value in kwargs.items()
            if (value is not None or value == {})}


Instruction:
Can you generate a brief explanation for the following Python 3 code
def manual_argument_parsing(argv):

    # Special case these for a better error message
    if not argv or argv == ['-h'] or argv == ['--help']:
        print_help_and_exit()

    try:
        dashdash_index = argv.index('--')
    except ValueError:
        print_std_err('Must separate command by `--`')
        print_help_and_exit()

    patches, cmd = argv[:dashdash_index], argv[dashdash_index + 1:]

    if '--help' in patches or '-h' in patches:
        print_help_and_exit()

    if '--all' in patches:
        all_patches = True
        patches.remove('--all')
    else:
        all_patches = False

    unknown_options = [patch for patch in patches if patch.startswith('-')]
    if unknown_options:
        print_std_err('Unknown options: {!r}'.format(unknown_options))
        print_help_and_exit()

    if patches and all_patches:
        print_std_err('--all and patches specified: {!r}'.format(patches))
        print_help_and_exit()

    return Arguments(all=all_patches, patches=tuple(patches), cmd=tuple(cmd))

Response: sadness because argparse doesn t quite do what we want.


Instruction:
Write a Python 3 function that can
create a console_script entry point for your application.

Response:
def make_entry_point(patches, original_entry_point):
    """Use this to make a console_script entry point for your application
    which applies patches.
    :param patches: iterable of pymonkey patches to apply.  Ex: ('my-patch,)
    :param original_entry_point: Such as 'pip'
    """
    def entry(argv=None):
        argv = argv if argv is not None else sys.argv[1:]
        return main(
            tuple(patches) + ('--', original_entry_point) + tuple(argv)
        )

    return entry


Instruction:
Implement a function in Python 3 to
return the client object for this storage instance.

Response:
def client(self):
        """
        Storage client

        Returns:
            client
        """
        if self._client is None:
            self._client = self._get_client()
        return self._client


Instruction:
Given the following Python 3 function, write the documentation
def exists(self, path=None, client_kwargs=None, assume_exists=None):
        try:
            self.head(path, client_kwargs)
        except ObjectNotFoundError:
            return False
        except ObjectPermissionError:
            if assume_exists is None:
                raise
            return assume_exists
        return True

Response: Check if a file exists in the object store.


Instruction:
Here you have a function in Python 3, explain what it does
def getctime(self, path=None, client_kwargs=None, header=None):
        return self._getctime_from_header(
            self.head(path, client_kwargs, header))

Response: Get the creation time of path.


Instruction:
Create a Python 3 function for
returning the time of last access of path.

Response:
def getmtime(self, path=None, client_kwargs=None, header=None):
        """
        Return the time of last access of path.

        Args:
            path (str): File path or URL.
            client_kwargs (dict): Client arguments.
            header (dict): Object header.

        Returns:
            float: The number of seconds since the epoch
                (see the time module).
        """
        return self._getmtime_from_header(
            self.head(path, client_kwargs, header))


Instruction:
How would you code a function in Python 3 to
get time from header

Response:
def _get_time(header, keys, name):
        """
        Get time from header

        Args:
            header (dict): Object header.
            keys (tuple of str): Header keys.
            name (str): Method name.

        Returns:
            float: The number of seconds since the epoch
        """
        for key in keys:
            try:
                date_value = header.pop(key)
            except KeyError:
                continue
            try:
                # String to convert
                return to_timestamp(parse(date_value))
            except TypeError:
                # Already number
                return float(date_value)
        raise UnsupportedOperation(name)


Instruction:
Explain what the following Python 3 code does
def getsize(self, path=None, client_kwargs=None, header=None):
        return self._getsize_from_header(self.head(path, client_kwargs, header))

Response: Returns the size in bytes of the object at path.


Instruction:
Can you generate the documentation for the following Python 3 function
def _getsize_from_header(self, header):
        # By default, assumes that information are in a standard HTTP header
        for key in self._SIZE_KEYS:
            try:
                return int(header.pop(key))
            except KeyError:
                continue
        else:
            raise UnsupportedOperation('getsize')

Response: Return the size in bytes from the header.


Instruction:
Write a Python 3 function for
checking if a path is an existing directory.

Response:
def isdir(self, path=None, client_kwargs=None, virtual_dir=True,
              assume_exists=None):
        """
        Return True if path is an existing directory.

        Args:
            path (str): Path or URL.
            client_kwargs (dict): Client arguments.
            virtual_dir (bool): If True, checks if directory exists virtually
                if an object path if not exists as a specific object.
            assume_exists (bool or None): This value define the value to return
                in the case there is no enough permission to determinate the
                existing status of the file. If set to None, the permission
                exception is reraised (Default behavior). if set to True or
                False, return this value.

        Returns:
            bool: True if directory exists.
        """
        relative = self.relpath(path)
        if not relative:
            # Root always exists and is a directory
            return True

        if path[-1] == '/' or self.is_locator(relative, relative=True):
            exists = self.exists(path=path, client_kwargs=client_kwargs,
                                 assume_exists=assume_exists)
            if exists:
                return True

            # Some directories only exists virtually in object path and don't
            # have headers.
            elif virtual_dir:
                try:
                    next(self.list_objects(relative, relative=True,
                                           max_request_entries=1))
                    return True
                except (StopIteration, ObjectNotFoundError,
                        UnsupportedOperation):
                    return False
        return False


Instruction:
Create a Python 3 function to
check if a file exists.

Response:
def isfile(self, path=None, client_kwargs=None, assume_exists=None):
        """
        Return True if path is an existing regular file.

        Args:
            path (str): Path or URL.
            client_kwargs (dict): Client arguments.
            assume_exists (bool or None): This value define the value to return
                in the case there is no enough permission to determinate the
                existing status of the file. If set to None, the permission
                exception is reraised (Default behavior). if set to True or
                False, return this value.

        Returns:
            bool: True if file exists.
        """
        relative = self.relpath(path)
        if not relative:
            # Root always exists and is a directory
            return False

        if path[-1] != '/' and not self.is_locator(path, relative=True):
            return self.exists(path=path, client_kwargs=client_kwargs,
                               assume_exists=assume_exists)
        return False


Instruction:
Write a Python 3 function for
returning object HTTP header.

Response:
def head(self, path=None, client_kwargs=None, header=None):
        """
        Returns object HTTP header.

        Args:
            path (str): Path or URL.
            client_kwargs (dict): Client arguments.
            header (dict): Object header.

        Returns:
            dict: HTTP header.
        """
        if header is not None:
            return header
        elif client_kwargs is None:
            client_kwargs = self.get_client_kwargs(path)
        return self._head(client_kwargs)


Instruction:
Write a Python 3 function that can
get path relative to storage.

Response:
def relpath(self, path):
        """
        Get path relative to storage.

        args:
            path (str): Absolute path or URL.

        Returns:
            str: relative path.
        """
        for root in self.roots:
            # Root is regex, convert to matching root string
            if isinstance(root, Pattern):
                match = root.match(path)
                if not match:
                    continue
                root = match.group(0)

            # Split root and relative path
            try:
                relative = path.split(root, 1)[1]
                # Strip "/" only at path start. "/" is used to known if
                # path is a directory on some cloud storage.
                return relative.lstrip('/')
            except IndexError:
                continue

        return path


Instruction:
Write a Python 3 function for
returning True if path refer to a locator.

Response:
def is_locator(self, path, relative=False):
        """
        Returns True if path refer to a locator.

        Depending the storage, locator may be a bucket or container name,
        a hostname, ...

        args:
            path (str): path or URL.
            relative (bool): Path is relative to current root.

        Returns:
            bool: True if locator.
        """
        if not relative:
            path = self.relpath(path)
        # Bucket is the main directory
        return path and '/' not in path.rstrip('/')


Instruction:
How would you implement a function in Python 3 that
splits the path into a pair of locator and tail.

Response:
def split_locator(self, path):
        """
        Split the path into a pair (locator, path).

        args:
            path (str): Absolute path or URL.

        Returns:
            tuple of str: locator, path.
        """
        relative = self.relpath(path)
        try:
            locator, tail = relative.split('/', 1)
        except ValueError:
            locator = relative
            tail = ''
        return locator, tail


Instruction:
Here you have a function in Python 3, explain what it does
def make_dir(self, path, relative=False):
        if not relative:
            path = self.relpath(path)
        self._make_dir(self.get_client_kwargs(self.ensure_dir_path(
            path, relative=True)))

Response:
Make a directory.

        Args:
            path (str): Path or URL.
            relative (bool): Path is relative to current root.


Instruction:
How would you explain what the following Python 3 function does
def remove(self, path, relative=False):
        if not relative:
            path = self.relpath(path)
        self._remove(self.get_client_kwargs(path))

Response: Remove an object from the cache.


Instruction:
How would you code a function in Python 3 to
ensure the path is a dir path.

Response:
def ensure_dir_path(self, path, relative=False):
        """
        Ensure the path is a dir path.

        Should end with '/' except for schemes and locators.

        Args:
            path (str): Path or URL.
            relative (bool): Path is relative to current root.

        Returns:
            path: dir path
        """
        if not relative:
            rel_path = self.relpath(path)
        else:
            rel_path = path

        # Locator
        if self.is_locator(rel_path, relative=True):
            path = path.rstrip('/')

        # Directory
        elif rel_path:
            path = path.rstrip('/') + '/'
        # else: root
        return path