Map the Py Editor interface point by point

Py Editor for Mac · Developer ID 27.0.2 (32) · review started 15 September 2026

This reference maps the persistent controls in a project window. It tells you where a control is, what it changes and where to find the complete procedure. Start with the real workspace overview, then read the numbered zones below from the top of the window toward the status bar.

This is a map, not a claim that every operation succeeds. A link marked with a limitation leads to the observed build-32 behavior. Controls that appear only in a particular state are listed with that prerequisite.

The project window in eleven zones

1. macOS window controls: close, minimize and full-screen controls for this project window. Closing a window is not the same as quitting the app.
2. Project menu: the project name and routes to Project Settings, the launcher, other projects and Finder.
3. Git control: repository creation or the current branch and repository actions.
4. Run controls: the active run configuration, Run, Debug and Application Settings.
5. Left rail: Project, Find, Commit and Learn in the upper group; Structure and Bookmarks in the lower group; More Tool Windows and Project Settings.
6. Left panels: the content selected by the Left rail. One upper and one lower panel can be visible together.
7. Editor tab bar: open-file tabs, close controls, per-tab Editor/Split/Preview modes and tab options.
8. Editor surface: the editable source or document view, with a preview beside it when Split is supported.
9. Results: Execution and the Tests, Coverage, Profiler, Terminal, Problems, Packages and Git log surfaces.
10. Right rail and panel: AI Assistant, Services, Ollama and the Product Feedback action.
11. Status bar: current activity, Results recovery, version, Helper, cursor/file facts and interpreter state.

The Left rail is not the same as the Left panels, and the Results selectors are not additional editor tabs. See the panel-by-panel guide for the purpose and reviewed boundary of every panel.

Top toolbar, from left to right

• Project name opens Project Settings, shows the Project panel, opens or creates projects, starts clone setup, reveals the folder and lists recent projects. New Python Project opens the launcher. Clone was inspected and cancelled without network or file creation. See getting started.
• Git control creates a local repository when none exists. In a repository it shows branch, working-tree, commit, history and remote commands. Local initialize, commit, history and branch switching are verified. Fetch, pull, push and conflict recovery are not. See Git.
• Active run configuration chooses Current Selected File or a named configuration, offers Run in Python Console and opens configuration editing. A named configuration delivered its saved arguments, environment value and working directory. See Run settings.
• Run starts the active configuration; while that execution is active, the same location can become Stop. Opening the Run panel does not start code. See Run and output.
• Debug starts or restarts debugging when the selected configuration and Helper state allow it. Later visual starts failed and opened interactive pdb; identify the actual interface. See debugging.
• Application Settings opens settings that apply across projects. Project-specific Interpreter, Run, Tasks and Editor controls are elsewhere. See the two settings locations.

Left rail and its two panel slots

The upper and lower groups are separated by a divider. Selecting another control in one group replaces only that group's content.

• Project opens the file tree in the upper slot. See Files and saved copies.
• Find opens project-wide search and replacement in the upper slot. See Find across a project.
• Commit opens working-tree changes, a diff and local commit controls in the upper slot. See Track changes with Git.
• Learn opens bundled lessons, guides and examples in the upper slot. See Learn and examples.
• Structure opens symbols from the current file in the lower slot. See Jump to a function or class.
• Bookmarks opens saved locations and breakpoint rows in the lower slot. See Keep and revisit a bookmark.
• More Tool Windows opens any available Left, Results or Right panel and configures which buttons are visible. See Tool Windows settings.
• Project Settings opens Interpreter, Run, Tasks and Editor settings for this project. See Project Settings.

Each visible panel header contains its title and Manage panel. Depending on the panel and its current state, that menu can offer Minimize, Open in Window, Dock in Workspace, Remove from Toolbar and Project-only collapse behavior. Use the actual menu instead of assuming every panel supports every action. Detached Project, Structure and Execution windows did not return after a normal restart in this build; follow the documented recovery.

Editor tabs and document-view controls

View mode belongs to the selected tab, not the entire project. In the reviewed build, active preview tabs and their modes did not survive a full app restart; reopen the file and select its mode again. See document previews and moving between tabs.

Results header and Execution tabs

Results is the complete Bottom area. Its first selector, Run, opens the Execution group with three inner tabs.

Inside Execution, Run, Debug and Python Console have their own action buttons and output. They do not share the same session lifetime. Terminal and Python Console sessions can disappear when the Bottom area is hidden or another tool is selected. Read the session-lifetime warning.

Right rail and right-side content

Only one Right panel is shown at a time. Provider and model selectors belong to AI Assistant content; they are not global toolbar controls. See AI Assistant, Services and the feedback procedure.

Status bar, from left to right

The displayed values change with the document and project. See status-bar details and Helper.

Panel-local controls, point by point

The rail selects a panel; the controls inside that panel act on its own content. Availability can change with the selected file, Helper, project environment, subscription and whether a task is running.

Shared panel header

• Panel title names the content below it. A detached window can move the title into the macOS title bar instead.
• Manage panel provides only actions supported by that panel and state: Minimize, Open in Window or Dock in Workspace, Remove from Toolbar and, for Project, Collapse All.
• Set up Helper can replace an unavailable Helper-dependent panel action. It opens setup; it is not evidence that setup or an installation completed.

Left-panel controls

• Project: New creates a Python file. Collapse All is in Manage panel. The tree opens folders or files; its context menu contains the relevant file operations, including copy-path choices and guarded rename, trash or discard actions. See Files and saved copies.
• Find: Find in project holds the query; Clear resets it; Show Replace adds Replace with, Replace for the selected match and All for a confirmed project-wide replacement. Before a query, Find in Project, Replace in Project and conditional Find Usages cards expose the same routes. See Find and replace.
• Commit: Refresh reloads Git state; when Helper is unavailable it is replaced by Set up Helper. Include all changed files and each file checkbox choose commit contents. A file row opens its working-tree diff. The lower area has Commit Message, Amend, Push and Commit/Amend. Conflict states add open-conflict, Mark Resolved and abort controls. Remote operations and conflict recovery are not verified. See Git.
• Learn: the header's book button opens the separate Python book. Course, Using Py Editor and Example Scripts disclosures expose lesson rows. A course can show Continue and Mark complete/Mark incomplete. See Learn.
• Structure: there is no separate local toolbar. Select a symbol row to reveal its line in the current readable source file.
• Bookmarks: Add bookmark records the current cursor location; Breakpoint toggles a Python breakpoint. Select a row to reveal it, or use its remove button. A conditional breakpoint is edited in the editor ruler, not in this local bar. The reviewed empty state contains one untranslated Italian footnote meaning that bookmarks appear with a file-and-line reference; this is a presentation defect, not an additional control.

Results control gutters and local bars

• Run: Run active configuration, Stop, Clear output, Soft wrap and Scroll to end. A program that requests input adds Enter input and Send inside the output surface.
• Debug: Start or restart debugger, Toggle breakpoint at cursor, Show breakpoints, Continue, Step into, Step over, Step out, Quit debugger and Clear debugger output. Step controls require a paused debugger. See the known build-32 debugging boundary.
• Python Console: Run active configuration in Python Console, Refresh variables, New Python Console, Interrupt, Stop Python Console, Clear console output, Soft wrap and Scroll to end. Stop is available only while the console is active.
• Tests: gutter Run tests and Stop; local Results and Raw output tabs, count/exit summary, Rerun Failed and Run. A result row reveals its file; its context menu can run that test alone.
• Coverage: gutter Run coverage and Stop; local Report and Raw output tabs, summary and Run. Show Coverage in Editor enables the green/red editor overlay after a report exists.
• Profiler: gutter Profile active configuration, Stop and Clear profiler results; local Call statistics, Raw output and Run. Results add function/file search, Project files only and Cumulative/Self time/Calls sorting. Profiler access can depend on the distribution entitlement.
• Terminal: New session, Interrupt, Soft wrap and Scroll to end. A new session is a restart, not an additional side-by-side terminal.
• Problems: Reanalyse. Empty or failed states can instead show Analyze Now/Again, Try Again, setup recovery or Open Run. Select a diagnostic to reveal its file and position.
• Packages: Refresh reloads environment and related repository state. Installed, PyPI, Disk, VCS and Sources content adds search, package details, update/install, copy-name and source-management actions. Installation and updates remain separately gated; see Packages.
• Git log: Refresh history. Select a commit to inspect its metadata and changed files; this surface is local history, not a remote push log.

Right-panel controls

• AI Assistant: provider, model and Chat/Agent mode selectors; Assistant actions with Refresh Models and provider configuration; connection status; copy-response; prompt, current-context label and Send. Agent output can add Review changes before any edit is applied. See AI Assistant.
• Services: Docker, Google Cloud, Amazon Web Services and Microsoft Azure navigation. Conditional content can add refresh, sign-in/out, profile or subscription choice, project link/unlink and Docker Start/Stop/Restart. Cloud operations are not verified and can require Pro, Helper and external CLIs.
• Ollama: connection status and Check Ollama again; Installed and Available model tabs; catalog search, model-name field, Download/Cancel and library link; selected-model details and Use in AI Assistant. When the server is unavailable, Download Ollama and Check Again replace the model browser. See local-provider setup.

The controls above are the active control map, not a blanket success result. Their linked chapters identify which operations were replayed, cancelled, blocked, failed or intentionally not run.

Welcome launcher, point by point

Choose File → Show Project Launcher to open Welcome to Py Editor. It is a project chooser, not an editor window.

1. App icon, name and version identify the running Py Editor build. The subtitle describes the app; these elements do not open a project.
2. Search a workspace, or type a path… filters Py Editor's known projects by name, pyproject.toml description or path. It does not browse arbitrary disk paths. Press Command-K to return focus to it.
3. Clear workspace search appears at the right of a non-empty query and returns to the unfiltered recent list.
4. New Python Project opens the macOS save dialog. Save As names the new folder, Where chooses its parent, Create writes starter main.py and pyproject.toml files, and Cancel creates nothing.
5. Clone Repository opens a sheet with Repository URL, Save in, Choose…, Cancel and Clone. Clone stays unavailable until the URL supplies a usable repository name. The reviewed procedure cancelled before any network request or file creation; authentication, errors and a completed clone are not verified.
6. Open Project opens the macOS folder chooser. Use this control for a local folder that does not yet appear in the launcher.
7. RECENTLY OPENED shows at most six project cards. A search changes the heading to RESULTS and can expose matches beyond those six cards. The caption reports how many entries are shown and known.
8. Project card shows a project name and either its manifest description or path. Click it to open the project. Up/Down selection is present in the active implementation; Return opening the selected search result was verified.
9. Remove from Projects is the card's context-menu action. It was not selected during this review; do not confuse it with deleting a project folder.
10. No workspaces yet or No workspace matches replaces the card list when there is nothing to show. A no-match result does not prove that a disk folder is missing.
11. macOS window controls close, minimize or enlarge only the launcher. An already open project continues in its own window.

Follow the illustrated launcher, clone and new-project procedures before relying on a control whose boundary is listed above.

Application Settings navigation, point by point

Open the gear at the right of the project toolbar. The left sidebar is the navigation and stays visible; selecting a row replaces the detail area. This Developer ID build has the nine rows below. It does not show Subscription, which is inserted only in an App Store commerce channel.

There is no settings-wide Save button. Ordinary preference changes are applied as they are made; account, credential, Helper and deletion actions have their own buttons and boundaries. The manual verified representative settings, not every value or remote transition. No cloud API key was entered, no account was changed, no Helper was installed or removed, and usage data was not deleted. See the complete Application Settings reference.

Project Settings navigation, point by point

Open Project Settings from the project-name menu, the Left rail, the status bar interpreter item, or Edit Configurations… for the Run section. Unlike Application Settings, this is a project-specific sheet with Cancel and Save.

1. Header identifies the current section, project name, path and access state. A conditional Open Project action appears when project access must be recovered.
2. Interpreter selects Project .venv, Embedded or Custom Python. Its detail reports Python, executable, version requirement and .venv readiness. Conditional controls choose a custom executable, refresh Helper state or open the Helper download route. In this build, a known executable Homebrew Python 3.14.6 remained rejected as Path is not executable even after native-picker selection; see the Interpreter limitation.
3. Run opens Run/Debug Configurations. Its list has Add, Copy and Remove; a row menu can Rename, Duplicate or Delete. The editor contains configuration name, script, working directory, arguments, environment variables and Terminal working directory, with chooser controls where appropriate.
4. Tasks stores argument fields for Compile, Tests, Ruff, Mypy and Analyze. Saved Test arguments were not honored by the reviewed Project Actions → Run Tests route; follow the documented limitation.
5. Editor enables project language features and reports analyzer readiness. When Pyright is missing and the other prerequisites are satisfied, opening this settings flow can start its installation separately from Save. Cancel is therefore not a promise to undo a package installation.
6. Cancel closes the sheet and discards the ordinary unsaved form draft. It does not reverse a separately started installation or external action.
7. Save validates the visible draft and writes the project settings. It stays unavailable when the selected interpreter, run configuration or argument syntax has a blocking error. A successful Save is not proof that a custom Python can run the project.

See Project Settings for every field, validation message and verified boundary.

Detached windows and external surfaces

• Detached panel window contains the same panel content, standard macOS window controls and Manage panel → Dock in Workspace. Closing it or restarting with it detached can require rail or Results recovery; Project, Structure and Execution each failed to restore automatically in the reviewed build. See workspace detachment.
• Python book is a separate Learn window with chapter navigation and an Open action for bundled material. See Learn.
• External example GUI belongs to the Python program being run, not to the Py Editor panel system. Focus Studio is one such example; see Focus Studio.

GUI-map coverage boundary

This chapter now maps the persistent project window, launcher, both settings surfaces, detached-panel shell and the distinction between app and example windows. Conditional states are named when they materially change a control. Every possible error, credential, account, installer and remote-service state still requires its linked procedure and evidence. Source-only controls are not promoted to live verification.