Instruction:
How would you explain what the following Python 3 function does
def flatten_reducer(
        flattened_list: list,
        entry: typing.Union[list, tuple, COMPONENT]
) -> list:
    """
    Flattens a list of COMPONENT instances to remove any lists or tuples
    of COMPONENTS contained within the list

    :param flattened_list:
        The existing flattened list that has been populated from previous
        calls of this reducer function
    :param entry:
        An entry to be reduced. Either a COMPONENT instance or a list/tuple
        of COMPONENT instances
    :return:
        The flattened list with the entry flatly added to it
    """

    if hasattr(entry, 'includes') and hasattr(entry, 'files'):
        flattened_list.append(entry)
    elif entry:
        flattened_list.extend(entry)
    return flattened_list

Response: Flattens a list of COMPONENT instances to remove any lists or tuples of COMPONENTS contained within the list


Instruction:
Make a summary of the following Python 3 code
def combine_lists_reducer(
        key: str,
        merged_list: list,
        component: COMPONENT
) -> list:
    """
    Reducer function to combine the lists for the specified key into a
    single, flat list

    :param key:
        The key on the COMPONENT instances to operate upon
    :param merged_list:
        The accumulated list of values populated by previous calls to this
        reducer function
    :param component:
        The COMPONENT instance from which to append values to the
        merged_list
    :return:
        The updated merged_list with the values for the COMPONENT added
        onto it
    """

    merged_list.extend(getattr(component, key))
    return merged_list

Response:
Reducer function to combine the lists for the specified key into a single list of values populated by previous calls to the this
   .


Instruction:
Make a summary of the following Python 3 code
def listen(self):
        '''Listen for events as they come in'''
        try:
            self._pubsub.subscribe(self._channels)
            for message in self._pubsub.listen():
                if message['type'] == 'message':
                    yield message
        finally:
            self._channels = []

Response: Listen for events as they come in


Instruction:
How would you explain what the following Python 3 function does
def thread(self):
        '''Run in a thread'''
        thread = threading.Thread(target=self.listen)
        thread.start()
        try:
            yield self
        finally:
            self.unlisten()
            thread.join()

Response: Run in a thread


Instruction:
Explain what the following Python 3 code does
def on(self, evt, func):
        '''Set a callback handler for a pubsub event'''
        if evt not in self._callbacks:
            raise NotImplementedError('callback "%s"' % evt)
        else:
            self._callbacks[evt] = func

Response: Set a callback handler for a pubsub event


Instruction:
Can you tell what is the following Python 3 function doing
def get(self, option, default=None):
        '''Get a particular option, or the default if it's missing'''
        val = self[option]
        return (val is None and default) or val

Response: Get a particular option or the default if it s missing


Instruction:
Given the following Python 3 function, write the documentation
def pop(self, option, default=None):
        '''Just like `dict.pop`'''
        val = self[option]
        del self[option]
        return (val is None and default) or val

Response: Just like dict. pop


Instruction:
Explain what the following Python 3 code does
def touch_project():
    r = Response()
    project = cd.project.get_internal_project()

    if project:
        project.refresh()
    else:
        r.fail(
            code='NO_PROJECT',
            message='No open project to refresh'
        )

    return r.update(
        sync_time=sync_status.get('time', 0)
    ).flask_serialize()

Response: Touches the project to trigger refreshing its cauldron. json state.


Instruction:
Explain what the following Python 3 code does
def fetch_synchronize_status():
    r = Response()
    project = cd.project.get_internal_project()

    if not project:
        r.fail(
            code='NO_PROJECT',
            message='No open project on which to retrieve status'
        )
    else:
        with open(project.source_path, 'r') as f:
            definition = json.load(f)

        result = status.of_project(project)
        r.update(
            sync_time=sync_status.get('time', 0),
            source_directory=project.source_directory,
            remote_source_directory=project.remote_source_directory,
            status=result,
            definition=definition
        )

    return r.flask_serialize()

Response:
Returns the synchronization status information for the currently opened
    project


Instruction:
Write a Python 3 function that can
download the specified file if it exists

Response:
def download_file(filename: str):
    """ downloads the specified project file if it exists """

    project = cd.project.get_internal_project()
    source_directory = project.source_directory if project else None

    if not filename or not project or not source_directory:
        return '', 204

    path = os.path.realpath(os.path.join(
        source_directory,
        '..',
        '__cauldron_downloads',
        filename
    ))

    if not os.path.exists(path):
        return '', 204

    return flask.send_file(path, mimetype=mimetypes.guess_type(path)[0])


Instruction:
Explain what the following Python 3 code does
def get_project_source_path(path: str) -> str:

    path = environ.paths.clean(path)

    if not path.endswith('cauldron.json'):
        return os.path.join(path, 'cauldron.json')

    return path

Response: Converts the given path into a project source path to the cauldron. json file.


Instruction:
How would you code a function in Python 3 to
load the cauldron. json project definition file for the given path.

Response:
def load_project_definition(path: str) -> dict:
    """
    Load the cauldron.json project definition file for the given path. The
    path can be either a source path to the cauldron.json file or the source
    directory where a cauldron.json file resides.

    :param path:
        The source path or directory where the definition file will be loaded
    """

    source_path = get_project_source_path(path)
    if not os.path.exists(source_path):
        raise FileNotFoundError('Missing project file: {}'.format(source_path))

    with open(source_path, 'r') as f:
        out = json.load(f)

    project_folder = os.path.split(os.path.dirname(source_path))[-1]
    if 'id' not in out or not out['id']:
        out['id'] = project_folder

    return out


Instruction:
How would you implement a function in Python 3 that
simplifies a path by replacing path prefixes with values specified by path_prefixes in the list of path_prefixes.

Response:
def simplify_path(path: str, path_prefixes: list = None) -> str:
    """
    Simplifies package paths by replacing path prefixes with values specified
    in the replacements list

    :param path:
    :param path_prefixes:
    :return:
    """

    test_path = '{}'.format(path if path else '')
    replacements = (path_prefixes if path_prefixes else []).copy()
    replacements.append(('~', os.path.expanduser('~')))

    for key, value in replacements:
        if test_path.startswith(value):
            return '{}{}'.format(key, test_path[len(value):])

    return test_path


Instruction:
How would you code a function in Python 3 to
convert a module entry into a package data dictionary with information about the module.

Response:
def module_to_package_data(
        name: str,
        entry,
        path_prefixes: list = None
) -> typing.Union[dict, None]:
    """
    Converts a module entry into a package data dictionary with information
    about the module. including version and location on disk

    :param name:
    :param entry:
    :param path_prefixes:
    :return:
    """

    if name.find('.') > -1:
        # Not interested in sub-packages, only root ones
        return None

    version = getattr(entry, '__version__', None)
    version = version if not hasattr(version, 'version') else version.version
    location = getattr(entry, '__file__', sys.exec_prefix)

    if version is None or location.startswith(sys.exec_prefix):
        # Not interested in core packages. They obviously are standard and
        # don't need to be included in an output.
        return None

    return dict(
        name=name,
        version=version,
        location=simplify_path(location, path_prefixes)
    )


Instruction:
Make a summary of the following Python 3 code
def get_system_data() -> typing.Union[None, dict]:

    site_packages = get_site_packages()
    path_prefixes = [('[SP]', p) for p in site_packages]
    path_prefixes.append(('[CORE]', sys.exec_prefix))

    packages = [
        module_to_package_data(name, entry, path_prefixes)
        for name, entry in list(sys.modules.items())
    ]

    python_data = dict(
        version=list(sys.version_info),
        executable=simplify_path(sys.executable),
        directory=simplify_path(sys.exec_prefix),
        site_packages=[simplify_path(sp) for sp in site_packages]
    )

    return dict(
        python=python_data,
        packages=[p for p in packages if p is not None]
    )

Response: Returns a dictionary containing information about the Cauldron system.


Instruction:
Can you generate the documentation for the following Python 3 function
def remove(path: str, max_retries: int = 3) -> bool:
    if not path:
        return False

    if not os.path.exists(path):
        return True

    remover = os.remove if os.path.isfile(path) else shutil.rmtree

    for attempt in range(max_retries):
        try:
            remover(path)
            return True
        except Exception:
            # Pause briefly in case there's a race condition on lock
            # for the target.
            time.sleep(0.02)

    return False

Response: Removes the specified path from the local filesystem if it exists.


Instruction:
Make a summary of the following Python 3 code
def end(code: int):

    print('\n')
    if code != 0:
        log('Failed with status code: {}'.format(code), whitespace=1)
    sys.exit(code)

Response: Ends the application with the specified error code.


Instruction:
How would you explain what the following Python 3 function does
def folder(self) -> typing.Union[str, None]:

        if 'folder' in self.data:
            return self.data.get('folder')
        elif self.project_folder:
            if callable(self.project_folder):
                return self.project_folder()
            else:
                return self.project_folder
        return None

Response: Returns the folder of the file that is used to store the file.


Instruction:
Here you have a function in Python 3, explain what it does
def project_exists(response: 'environ.Response', path: str) -> bool:

    if os.path.exists(path):
        return True

    response.fail(
        code='PROJECT_NOT_FOUND',
        message='The project path does not exist',
        path=path
    ).console(
        """
        [ERROR]: Unable to open project. The specified path does not exist:

          {path}
        """.format(path=path)
    )
    return False

Response: Determines whether or not a project exists at the specified path.


Instruction:
Make a summary of the following Python 3 code
def update_recent_paths(response, path):

    try:
        recent_paths = environ.configs.fetch('recent_paths', [])

        if path in recent_paths:
            recent_paths.remove(path)

        recent_paths.insert(0, path)
        environ.configs.put(recent_paths=recent_paths[:10], persists=True)
        environ.configs.save()
    except Exception as error:  # pragma: no cover
        response.warn(
            code='FAILED_RECENT_UPDATE',
            message='Unable to update recently opened projects',
            error=str(error)
        ).console(whitespace=1)

    return True

Response: Updates the recent paths of the current project.


Instruction:
Can you tell what is the following Python 3 function doing
def split_line(line: str) -> typing.Tuple[str, str]:

    index = line.find(' ')
    if index == -1:
        return line.lower(), ''

    return line[:index].lower(), line[index:].strip()

Response: Splits the raw line into two strings.


Instruction:
Here you have a function in Python 3, explain what it does
def render_stop_display(step: 'projects.ProjectStep', message: str):
    stack = render_stack.get_formatted_stack_frame(
        project=step.project,
        error_stack=False
    )

    try:
        names = [frame['filename'] for frame in stack]
        index = names.index(os.path.realpath(__file__))
        frame = stack[index - 1]
    except Exception:
        frame = {}

    stop_message = (
        '{}'.format(message)
        if message else
        'This step was explicitly stopped prior to its completion'
    )

    dom = templating.render_template(
        'step-stop.html',
        message=stop_message,
        frame=frame
    )
    step.report.append_body(dom)

Response: Renders a stop action to the Cauldron display.


Instruction:
Write a Python 3 function for
identifying for the project.

Response:
def id(self) -> typing.Union[str, None]:
        """Identifier for the project."""
        return self._project.id if self._project else None


Instruction:
Make a summary of the following Python 3 code
def display(self) -> typing.Union[None, report.Report]:
        return (
            self._project.current_step.report
            if self._project and self._project.current_step else
            None
        )

Response: The display report for the current project.


Instruction:
Can you tell what is the following Python 3 function doing
def shared(self) -> typing.Union[None, SharedCache]:
        return self._project.shared if self._project else None

Response: The shared display object associated with this project.


Instruction:
Explain what the following Python 3 code does
def settings(self) -> typing.Union[None, SharedCache]:
        return self._project.settings if self._project else None

Response: The settings associated with this project.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def title(self, value: typing.Union[None, str]):
        if not self._project:
            raise RuntimeError('Failed to assign title to an unloaded project')
        self._project.title = value

Response: Sets the title of the project.


Instruction:
Here you have a function in Python 3, explain what it does
def load(self, project: typing.Union[projects.Project, None]):
        self._project = project

Response: Connects this object to the specified source project.


Instruction:
Write a Python 3 function for
creating an absolute path to the specified file or directory within the project source directory.

Response:
def path(self, *args: typing.List[str]) -> typing.Union[None, str]:
        """
        Creates an absolute path in the project source directory from the
        relative path components.

        :param args:
            Relative components for creating a path within the project source
            directory
        :return:
            An absolute path to the specified file or directory within the
            project source directory.
        """
        if not self._project:
            return None

        return environ.paths.clean(os.path.join(
            self._project.source_directory,
            *args
        ))


Instruction:
Write a Python 3 script for
stopping the execution of the project at the current step immediately holding the action.

Response:
def stop(self, message: str = None, silent: bool = False):
        """
        Stops the execution of the project at the current step immediately
        without raising an error. Use this to abort running the project in
        situations where some critical branching action should prevent the
        project from continuing to run.

        :param message:
            A custom display message to include in the display for the stop
            action. This message is ignored if silent is set to True.
        :param silent:
            When True nothing will be shown in the notebook display when the
            step is stopped. When False, the notebook display will include
            information relating to the stopped action.
        """
        me = self.get_internal_project()
        if not me or not me.current_step:
            return

        if not silent:
            render_stop_display(me.current_step, message)
        raise UserAbortError(halt=True)


Instruction:
Make a summary of the following Python 3 code
def get_internal_project(
            self,
            timeout: float = 1
    ) -> typing.Union['projects.Project', None]:
        """
        Attempts to return the internally loaded project. This function
        prevents race condition issues where projects are loaded via threads
        because the internal loop will try to continuously load the internal
        project until it is available or until the timeout is reached.

        :param timeout:
            Maximum number of seconds to wait before giving up and returning
            None.
        """
        count = int(timeout / 0.1)
        for _ in range(count):
            project = self.internal_project
            if project:
                return project
            time.sleep(0.1)

        return self.internal_project

Response: Attempts to return the internal project.


Instruction:
How would you code a function in Python 3 to
stop execution of the current node in the current notebook.

Response:
def stop(
            self,
            message: str = None,
            silent: bool = False,
            halt: bool = False
    ):
        """
        Stops the execution of the current step immediately without raising
        an error. Use this to abort the step running process if you want
        to return early.

        :param message:
            A custom display message to include in the display for the stop
            action. This message is ignored if silent is set to True.
        :param silent:
            When True nothing will be shown in the notebook display when the
            step is stopped. When False, the notebook display will include
            information relating to the stopped action.
        :param halt:
            Whether or not to keep running other steps in the project after
            this step has been stopped. By default this is False and after this
            stops running, future steps in the project will continue running
            if they've been queued to run. If you want stop execution entirely,
            set this value to True and the current run command will be aborted
            entirely.
        """
        step = self._step
        if not step:
            return

        if not silent:
            render_stop_display(step, message)
        raise UserAbortError(halt=halt)