def open(self, filepath=None):
        """Open a new file.

        filepath (pathlib.Path instance)
            Path to the file to be opened.
        """
        ### if no filepath is provided, prompt user to
        ### pick one from the file manager

        if not filepath:

            ## pick path

            paths = (
                select_paths(
                    caption=OPEN_FILE_CAPTION,
                    expecting_files_only=True,
                )
            )

            ## respond according to number of paths given

            length = len(paths)

            if length == 1:
                filepath = paths[0]

            elif length > 1:

                show_dialog_from_key(
                    "expected_single_path_dialog"
                )
                return

            else:
                filepath = None

        ### if even so the user didn't provide a filepath,
        ### return earlier
        if not filepath:
            return

        ### prompt user for action in case a file is provided
        ### but there are unsaved changes in the current one

        if filepath and not are_changes_saved():

            answer = (
                show_dialog_from_key(
                    "open_new_while_unsaved_dialog",
                )
            )

            if answer == "open new":
                pass
            elif answer == "save first":
                self.save()
            else:
                return

        ### store boolean indicating whether or not the given path
        ### is of a temporary file
        is_temp_file = (
            APP_REFS.temp_filepaths_man.is_temp_path(filepath)
        )

        ### TODO checks below should be made before the
        ### beginning of the "if" block, so that you
        ### can notify the user in case they don't work,
        ### instead of just reaching the end of the method
        ### silently (for instance, it would be good to
        ### notify user that the file is of the wrong
        ### extension if the corresponding condition
        ### indicates so);
        ###
        ### also, review this method to guarantee we deal
        ### properly with all possible use-cases of its
        ### usage; a simple flowchart on paper should
        ### probably enough to see all possible routes
        ### the execution flow may go;

        ### but if the user provided one existing regular
        ### file with the right extension, we start
        ### processing it for usage

        if (
            filepath.is_file()
            and filepath.suffix.lower() == NATIVE_FILE_EXTENSION
        ):

            ### perform actions depending on whether filepath is a
            ### temporary file or not

            if is_temp_file:
                swap_path = TEMP_FILE_SWAP

            else:

                ### before loading the file, let's check the
                ### preexistence of a swap file in the
                ### swap path attribute, since it might change
                ### how we'll approach the file loading

                ## generate swap path
                swap_path = get_swap_path(filepath)

                ## if swap file exists there might have been a
                ## crash which forced the program to exit,
                ## leaving the recent changes in the swap file
                ## before the user could save them; thus, we
                ## prompt the user to decide which action to
                ## perform:

                if swap_path.is_file():

                    answer = show_dialog_from_key("swap_exists_dialog")

                    # load original file (ignore swap)

                    if answer == "load_original":

                        swap_path.unlink()

                        source_contents = (
                            filepath.read_text(encoding="utf-8")
                        )

                        swap_path.write_text(
                            source_contents,
                            encoding="utf-8",
                        )

                    # load swap file (ignore original)

                    elif answer == "load_swap":

                        ### XXX review this block

                        ### TODO also prevent people from
                        ### - accidentaly - clicking the button
                        ### that leads here when the dialog
                        ### comes up;

                        # save backup for the filepath

                        save_timestamped_backup(
                            filepath,
                            USER_PREFS["NUMBER_OF_BACKUPS"],
                        )

                        # copy swap file contents into
                        # source file

                        swap_contents = swap_path.read_text(encoding="utf-8")

                        filepath.write_text(
                            swap_contents,
                            encoding="utf-8",
                        )

                    else:
                        return

            ### try loading the file, storing its data
            try:
                loaded_data = load_pyl(filepath)

            ### if loading fails abort opening the file by
            ### leaving this method after notifying the
            ### user of the problem

            except Exception as err:

                message = "An error occurred while trying to open a file."

                logger.exception(message)

                USER_LOGGER.exception(message)

                create_and_show_dialog(
                    (
                        "An error ocurred while trying to open"
                        f" {filepath}. Check the user log for details"
                        " (press Ctrl+Shift+j after leaving this dialog or"
                        " access the \"Help > Show user log\" option"
                        " on the menubar)."
                    ),
                    level_name="error",
                )

                return

            ### if the given filepath is temporary or the swap path
            ### for the regular file does not exist, we copy the
            ### source contents into it

            if is_temp_file or not swap_path.is_file():

                source_contents = filepath.read_text(encoding="utf-8")

                swap_path.write_text(
                    source_contents,
                    encoding="utf-8",
                )

            ### store both paths for access throughout the
            ### system

            ## store source path
            APP_REFS.source_path = filepath

            ## store swap path

            # admin task for regular files: remove existing swap
            # if present and different from the one being loaded
            # (this will happen when loading a file when there is
            # another one already loaded)

            if not is_temp_file:

                try:
                    current_swap = APP_REFS.swap_path

                except AttributeError:
                    pass

                else:

                    if not current_swap.samefile(swap_path):
                        current_swap.unlink()

            APP_REFS.swap_path = swap_path

            ### clean up native format data that may
            ### exist from previous session
            APP_REFS.data.clear()

            ### replace such data with new native format
            ### data loaded from the file to be opened
            APP_REFS.data = loaded_data

            ### if filepath is not temporary, store it as a recently
            ### open file, so it is available in the menubar under
            ### the "File > Open recent" submenu
            if not is_temp_file:
                store_recent_file(APP_REFS.source_path)

            ### finally,
            ### - prepare the application for a new session
            ### - indicate file as unsaved if it is temporary
            ### - draw the window manager
            ### - restart the loop making the window manager
            ###   the loop holder
            ###
            ### drawing is important here cause the user
            ### may accidentally keep the mouse over the
            ### menubar when the file finishes loading,
            ### which would make it so the menu would
            ### be the loop holder, thus the graph
            ### objects would not be initially drawn
            ### on the screen

            self.prepare_for_new_session()

            if is_temp_file:
                indicate_unsaved()

            self.draw()

            raise SwitchLoopException
Open a new file.

        filepath (pathlib.Path instance)
            Path to the file to be opened.
        
nodezator/winman/fileop.py