GETTING STARTED

Desktop workspace

Open Python files, convert them together, inspect any errors, and save the generated C.

Matte appearance and dialog controls

PyCForge uses a consistent matte graphite finish across the workspace, menus, dialogs, scan results, and Help. Silver-gray controls and steel-blue accents remain distinct from the darker code editors. The harpy eagle identifies the application; the blue C in the product lettering connects the brand to C conversion. High-resolution PNG icons are supplied for standard and scaled displays.

Buttons use solid surfaces. Hover, keyboard focus, pressed, checked, and disabled states remain visible. Error, warning, and success colors keep their usual meanings; a brighter button is not a conversion-status guarantee.

Double-clicking a title bar maximizes only dialogs that offer that control. In Classes & Functions, the copy-definition action sits beside the other title-bar tools; its overlapping-page icon represents Copy, not maximize. Settings and document commands retain their existing keyboard shortcuts and behavior.

Launch

pycforge-workspace

You can also run python -m pycforge.ide.

Opening the workspace

The startup progress dialog checks application resources and offline Help, prepares Ting review files, and compiles NumPy/Numba numerical routines in memory on a background worker. Saved numerical caches are not required. Cancel prevents the workspace from opening; preparation stops at a safe boundary.

Recoverable problems appear in a Startup report after the workspace opens. A warning icon and a selectable, read-only report use the same matte graphite theme as the workspace. It lists affected settings or files and explains the action taken. Use Copy report to retain the details. Invalid preferences use defaults. An unreadable or damaged settings store is left in place, with preferences held only for the current session. A failure in required application files or dependencies prevents launch and displays an error; reinstall from a complete release if those files are damaged.

For a clean start, run pycforge-workspace --safe-mode or python -m pycforge.ide --safe-mode. This opens an empty workspace with default preferences, without reading or updating the saved settings or previous file list. Restart normally to use them again. Safe start still checks required application resources.

Open, edit, and convert

1. Choose Open Python to select files, or New Module to start one. The first file becomes the primary module automatically.
2. Add every source file needed by imports. In Typed mode, each included module needs a supported function. Runtime mode also accepts empty or constants-only companions; its complete bundle needs at least one top-level function.
3. Edit the Python source and save it using Save Python or Save Python As.
4. Select Transpile → Typed, then click the Transpile button or press Ctrl+Return. It converts all open modules together.
5. On success, review Generated C. Choose Set C Destination, then Save Generated C.

Save Python in the toolbar and File menu is enabled for a new module or a selected module with unsaved edits. Both disable after a successful save and enable as soon as that module changes. Switching tabs updates them for the selected module. Save Python As… lets you choose another location for a saved module. Save commands are temporarily disabled while a Python save is in progress.

After a successful Save or Save As, the tab, Source Bundle row, source header, breadcrumb and window title show the saved filename. For example, saving a new module as geometry.py immediately gives its tab that name. Hover the tab to see the full path. The Source Bundle’s ID and LOGICAL fields remain the explicit conversion identities; saving under another filename does not rewrite imports. Cancelled or failed saves keep the previous name.

File → Save All Python saves every new or modified Python module without changing the selected tab. It skips unchanged files and asks for a location for each module that has never been saved. Cancelling a location dialog or encountering a write error stops the remaining saves; completed saves are kept and unsaved modules remain open. The command is also available from the command palette.

File → Project saves and opens portable .pcfproj bundles of your open modules, with a preview and named checkpoints. Bundle saves capture editor text separately from Python-file saves. See Projects and checkpoints for the complete save, load, and restore workflow.

Closing the workspace offers Save All, Discard, or Cancel when modules are unsaved. Closing during a save waits without freezing the editor. A cancelled or failed save leaves the workspace open. Edits made during saving remain unsaved and prevent automatic closure.

Both Python editor panes and Generated C use normal scrollbars, shown when their content needs scrolling. The Python overview marker rail is no longer displayed. Diagnostic selections stay inside the text viewport; the final line remains reachable, including with horizontal scrolling and folded functions. Find, source mapping navigation, and ForgeLens highlighting remain available. Generated C is read-only in the workspace. Make changes in Python and convert again. You can close any module tab, including the last one; the workspace may be empty.

Closing a tab removes that module from the Source Bundle; it does not delete the Python file on disk. After closing the last tab, choose Open Python or New Module to continue. Save or discard any modified source when prompted. Generated C can remain visible while you close tabs.

Fold and reveal functions

Click the Python gutter fold marker to collapse or expand a function. Edit → Folding Functions and the source header also provide Fold All and Unfold All. Large files may take a moment to analyze before folding becomes available.

Fold arrows describe Python function boundaries independently of conversion success. New or pasted valid functions receive arrows after source analysis, without a transpile. Switching modules restores the displayed source’s markers. Refreshing syntax colors preserves arrows and collapsed functions; actual text edits reveal affected content and refresh the boundaries. A rejected conversion does not prevent folding valid Python. Incomplete or invalid syntax cannot supply reliable new fold boundaries; correct the syntax and allow analysis to finish. Single-line functions have no body lines to hide. Bounded large-file mode disables folding.

Find, Go to Definition, and Classes & Functions reveal a destination hidden inside a fold while leaving unrelated folds alone. Folding or unfolding dismisses completion lists and parameter hints. Fold choices are temporary: closing and reopening a file does not restore its collapsed functions.

Professional Python editing

The Edit menu keeps Undo, Redo, and clipboard commands at the top, then groups Selection, Lines, Find and Replace, Code, and Folding Functions. Menus stay inside the monitor work area. On very short displays, a More Commands submenu keeps overflow commands reachable. The main toolbar remains compact.

Smart typing and multiple cursors

Enable Edit → Code → Smart Brackets and Quotes to insert matching pairs, wrap selected text, skip existing closing characters, and delete an empty pair with Backspace. Brackets inside comments and strings are not automatically paired. The preference is remembered.

Ctrl+D selects the current word; repeat it to add the next exact occurrence. Ctrl+Alt+L selects up to 256 occurrences. Alt+click adds a cursor at another location. Type, delete, paste, or move the cursors together. Consecutive typing is one undo step across the selected occurrences; paste is a separate step. Escape returns to one cursor. An ordinary click or editing from the other split pane clears extra cursors. Clipboard paste inserts the same text at each cursor.

Try multiple cursors: place the caret in amount, press Ctrl+D twice to select two occurrences, type total, then press Escape. Undo restores both edited occurrences together. Occurrence selection is text matching; use Rename Name when Python scope matters.

amount = 3
print(amount)

Classes and functions

Right-click a Python module tab or the line-number or fold-marker gutter to open Classes & Functions. The frameless dialog lists classes, methods, and nested functions in a themed tree. A panel with a short progress bar and no loading text covers the entire tree area until the list is ready. Selecting a row leaves the editor untouched; double-click or press Enter to go to its definition and reveal any enclosing fold.

The Copy icon at the left of the title bar copies the selected definition's full source, including decorators, documentation, body comments and existing indentation. Copy does not move the editor cursor or scroll, alter folding, or add an Undo step. A temporary label immediately to the right of Copy identifies the copied definition, then the normal title returns. Press Escape or the title-bar close button to dismiss the dialog.

This navigator scans only when opened, in a background process. It accepts up to 1 million characters and displays the first 4,096 definitions. Complete Python syntax is required. If the document changes, close and reopen the list before copying or navigating. No additional library is required.

Find and replace

Open Find or Replace with Ctrl+F or Ctrl+H. Enable Regex for Python regular expressions; ^ and $ match line boundaries. Replacement groups use \1 or \g<name>. Select source text before opening Find, then check In selection to restrict replacement to that captured range. Navigating search matches does not change the captured scope.

With Regex off, the search and replacement are literal text. Match case controls capitalization, and Whole word treats letters, digits, and underscores as word characters. Enter in Find or F3 visits the next result; Shift+F3 visits the previous one. Enter in Replace performs the current replacement. Escape closes the bar. Generated C supports finding only.

Example: change a numbered identifier. Open Replace, enable Regex and Match case, leave Whole word off, and enter:

item_12 = item_3 + item_12

Replace All produces:

entry_12 = entry_3 + entry_12

Enter the backslashes exactly as shown, without Python quotes or doubled escaping. Regex replacement also recognizes \n as a newline; a literal backslash uses \\. This is a text operation and can also match comments or strings. For a limited edit, select the intended lines before opening Replace and enable In selection.

After a paste or replacement, search results refresh against the new text. A captured selection tracks text replaced within it; close and reopen Find with a new selection to choose a different range. Navigating a folded match reveals it. Replace All is one Undo step in the current document. Invalid expressions and incomplete or oversized result sets do not apply a partial Replace All.

Edit → Find and Replace → Replace in Open Documents (Ctrl+Shift+H) previews changes across the currently open source bundle, including unsaved buffers. Review the document/line, current text, and replacement before Apply. Edits remain unsaved until you save explicitly, and each edited document has its own undo step. A changed document invalidates the preview. More than 2,000 matches cannot be applied; narrow the expression first.

Completion, navigation, and rename

Edit → Code → Complete Name (Ctrl+Space) offers offline Python names and members. Use Up/Down and Enter or Tab to accept, or Escape to dismiss. Parameter Hints (Ctrl+Shift+Space) shows the current call’s signature in the bottom status strip. Automatic hints use the same strip, so typing inside print() stays visible. Only clickable completion choices appear over the editor. Editing, moving the caret, folding, or changing focus dismisses an old hint; newer conversion status takes priority. Automatic suggestions can be switched off under Edit → Code. Completion assists normal Python editing; it does not promise that a suggested operation is supported by the transpiler.

Go to Definition (F12) resolves a name within the current document. Return to Previous Location (Alt+Left) returns to the prior editing position. Rename Name (F2) previews statically resolved references in the current document, preserving unrelated scopes, comments, and string literals. Imported bindings receive an alias without changing the external module/export. Bare dotted imports need an explicit alias first. Existing names and special protocol names are refused to avoid capture or altered Python protocols. Renames involving method inheritance, class-private name mangling, equivalent Unicode spellings, or decorated parameters are refused when their binding cannot be established safely. Dynamic string lookups and references in other documents need manual review.

Try rename: in def add(amount: int) -> int: with return amount + 1 in its body, place the caret on amount, press F2, enter total, and inspect the proposed edits before Apply. Both references change together; a comment containing the word amount stays as written. Undo restores the original binding.

If completion is absent, focus the Python editor, clear extra cursors with Escape, and try Ctrl+Space. Suggestions do not inspect your installed project packages or other open modules, so external-library names may be unavailable. Automatic requests wait briefly after typing. Folding, switching context, or editing again discards obsolete suggestions.

Explicit formatting

Edit → Code → Format contains Format Document (Alt+Shift+F) and Format Selection (Ctrl+K, then Ctrl+F). Selection formatting applies to the selected lines and retains unselected text. If a formatting change crosses the selection boundary, expand the selection before trying again. Formatting preserves comments and string values and is applied only if Python's syntax tree is unchanged. Invalid/incomplete Python must be corrected before formatting. Each formatting operation is undoable and runs only when requested.

Try formatting: paste the following into a Python source editor and run Format Document. It spaces the arguments and addition while preserving the function's behavior. Undo returns the original text. This editor example does not need to be converted.

def add(left:int,right:int)->int:
    return left+right

def add(left: int, right: int) -> int:
    return left + right

Limits and responsiveness

Jedi and autopep8 are installed with PyCForge and run offline. Source is never executed for editor assistance. Analysis and regex work run in separate processes with deadlines, allowing an expensive request to be cancelled independently of editing. Assistance/formatting accepts 500,000 characters per document; bundle search previews accept 64 documents and 4 million characters total. New edits invalidate pending results. These tools create no source backups, recovery copies, or automatic saves.

The editor reuses analysis of unchanged documents and defers passive analysis while you type. The outline is parsed in a cancellable background process, and folding markers use cached results while painting. Multiple-cursor selections are collected in one batch. New edits retire older results before they can affect current text. Saving retains existing permission modes and follows linked-file targets.

Advanced searches (Regex or In selection) and replacement previews show up to 2,000 matches. Literal Find in the current editor and Find in Source Bundle show up to 5,000. Narrow a search when its count reports omitted matches. A replacement batch that would remove and insert more than 1 million characters in total is refused before it changes any buffer.

Large pastes still require text insertion and layout on the GUI thread and can briefly pause the display. Background analysis cannot eliminate that cost. If an analysis command times out or reaches a size limit, use a smaller document or narrower search; an unavailable suggestion does not disable ordinary typing or saving.

Opening a workspace file accepts regular UTF-8 files up to 16 MiB. Larger files and special files are refused before loading; conversion and analysis retain their own smaller limits. Undo history is not a whole-application memory quota.

Convert runtime values

Open all required source documents, select Transpile → Runtime, then click the Transpile button or press Ctrl+Return. This mode supports the string, container, class, lambda, and comprehension forms in the runtime reference. To use typed conversion, select Transpile → Typed, then click Transpile.

The checkmark marks the selected mode, and only one mode can be selected. Selecting a mode does not start conversion. The choice is remembered between launches; Typed is the initial default. Changing modes makes previous output stale until conversion succeeds again. Both modes produce normal C files, with different C interfaces. Review the diagnostics before saving a result.

Check Python Code

Open the wrench dropdown after the text menus and choose Check Python Code…, above Run Python. Alt+T opens Tools. Scan checks the selected tab’s current text, including unsaved edits. A stage label, percentage bar and elapsed time show progress. The source is never executed or imported.

The checker combines Python syntax validation with four dedicated Ting rule packs. It follows supported module and function paths to find names used without values, unreachable statements, invalid uses of known or possible None, mismatched local-call arguments and shared mutable defaults. It follows arguments, aliases and return values through statically resolved helpers. Loop exits, exception handlers, finally and context-manager paths participate in the analysis. Findings distinguish confirmed issues, conditional warnings and review suggestions; messages identify relevant branches or helper locations.

Enable Use open modules to trace imports to include current editor text from companion tabs in the next scan. Only explicitly open modules participate. Names such as helpers.py or pkg/helpers.py identify imports; ambiguous names, re-exports and unresolved imports remain unknown. Findings stay on the selected tab, with helper locations in their messages. Changes to any supplied module invalidate the retained scan.

Click a panel to close the dialog and highlight its code in the original tab. Reopening retains panels and scroll position. Right-click an issue panel to remove it, or re-scan to refresh the results. Removing a panel only dismisses it; a re-scan may find it again. Editing, renaming or closing a scanned tab immediately disables its retained panels in both the full dialog and the recent-scan dropdown. Stale locations are labeled as scanned lines. Changes to included companion modules do the same. Undo does not revive old results; re-scan to obtain fresh findings. A scan that finishes after its source was edited also stays stale. Re-scan always uses the currently selected tab.

Cancel clears all panels and shows Scan was halted. Closing an active scan also cancels it. Completed results remain available while the workspace is open. There is no HTML export or automatic source editing.

Hover over the scan-status text for coverage notes. Limits are 16 supplied modules, 1 MiB each and 2 MiB total, 50,000 syntax nodes per module, 256 functions total, 200 displayed findings and 60 seconds. Calls are bounded to 10 levels and 512 contexts; flow work has a separate operation budget. Small known loops are followed directly, with conservative merging for other loops. Exceptions from unknown operations and suppression by custom context managers introduce uncertainty.

Dynamic runtime types, class-body execution, comprehensions/lambdas, async/generator bodies, match, except*, assignment-expression bodies and global/nonlocal mutation are outside full flow analysis. Recursive and expanded calls can remain unresolved. A clean scan means no issues found by the completed checks, not proof of correctness. This feature checks Python code quality only; it does not assess conversion compatibility. Consult the conversion documentation for supported conversion behavior.

The Tools control has two separate click areas. The wrench opens the usual Tools menu; the arrow opens a compact view of the latest Python scan in this workspace session. The compact view uses the same clickable issue panels and dismissed findings as the full dialog. Click a panel to navigate, right-click to remove it, or choose Open full scan. No scan, a scan in progress, a clean completed scan, and all findings dismissed each have distinct feedback. Changed or closed source blocks outdated navigation. Escape or clicking outside closes the dropdown.

Run Python

Choose Tools → Run Python… (F5) to open an editable command for the selected tab. A saved module supplies its absolute path automatically. The default uses the Python environment running PyCForge and sets the working directory to the module’s folder, so nearby imports and relative file paths work as they do when launched from that folder.

A new module or one with unsaved edits shows Run Python — Module not saved in the dialog titlebar. Its command box and Run button are disabled. Save the module from the workspace; the dialog updates after a successful save. Switching tabs also updates the dialog and resets the command to that tab’s saved path. Opening the dialog never saves or runs source automatically.

Edit the command to change the interpreter or add script arguments, then choose Run. Reset Command restores the selected module’s default. Windows uses cmd.exe /k and the console Python executable, including when PyCForge starts through pythonw.exe. Linux opens an installed terminal and waits for Enter after showing the exit code; macOS opens Terminal and returns to its prompt. The default keeps output and Python errors visible after execution. Edited commands follow the platform’s command syntax.

Linux needs an available terminal: x-terminal-emulator, GNOME Terminal, Konsole, Xfce Terminal, xterm, kitty, or Alacritty. The command runs as your user in an external terminal, with normal keyboard input and installed Python packages. It executes the saved Python script independently of transpilation and does not run generated C. Imported files are loaded from disk; save any edited companion modules before running.

Use Save All Python before running a script that imports edited modules. The script console is separate from PyCForge: closing it stops that run, and normal IDE shutdown does not wait for the script to finish. On Windows, closing the original console used to start PyCForge can terminate the IDE before its save prompts. Close the IDE from its own window first.

Compile C

After either Typed or Runtime transpilation, choose Transpile → Compile C… (Ctrl+Shift+Return) or the Compile toolbar button. Select a compiler family, its executable, target, output path, optimization and output kind. Each family remembers its executable and options. The compiler and output choosers accept binary filenames without loading source previews.

Compiler default uses the installed toolchain's target. An explicit target is checked against the compiler before building; GCC and MSVC require a driver or developer environment already configured for it. Clang can select a target, but needs that target's headers, libraries and linker. These profiles accept supported 64-bit Linux, Windows and macOS targets; the available list depends on the compiler family.

PCFC11 offers O0 and O1; GCC and Clang also offer O2 and O3; MSVC and Clang-cl offer O0, O1 and O2. The assembler/linker override belongs to PCFC11. Other profiles use their compiler driver for both compilation and linking. Compiler installations are separate from PyCForge; transpilation does not require one.

Executable entries have no Python parameters. Typed entries return int; Runtime entries return int or None. Integer exit codes outside 0–255 become 255; None becomes 0. Runtime or typed file errors return 1. The Runtime adapter initializes and destroys its context, including its owned values and file resources. Object output needs no entry function.

The build dialog shows stage timings, elapsed time, diagnostics and a bounded log. Use Cancel Build to stop compilation and Copy Report to capture results. Editing source or changing conversion mode invalidates the build. Failed, cancelled or stale builds preserve any existing output. Compilation never runs the generated program.

Understand conversion state

Inspect a conversion

The amber warning-triangle button beside Tools opens a quick list of conversion diagnostics after a rejected or failed conversion. Each row shows the same severity, code, source location and message as the Diagnostics tab. Click a row, or select it and press Enter, to open its module and highlight the reported source. Long messages have full tooltips; rows without a source location cannot navigate.

Editing either Python view immediately closes this list and disables the button. Renaming or closing source, changing the bundle, or starting another conversion also retires old navigation. Undoing an edit does not re-enable old diagnostics: convert again. Switching tabs alone keeps current diagnostics available. This shortcut does not change the Diagnostics tab or run a Python code scan.

Open Transpilation Details to see diagnostics and conversion details. Selecting a diagnostic highlights the affected Python. Both Typed and Runtime conversions provide source mappings and ForgeLens highlighting to locate corresponding C. Runtime mappings record exact emission origins and pass independent output/provenance checks. Runtime support code without a Python origin remains C-only.

The status-bar Ting control opens additional review feedback. See Understanding Ting feedback for what its findings and missing checks mean.

Search and navigate the workspace

• Find in Source Bundle (Ctrl+Shift+F) searches literal text across the already-open modules, including unsaved text. Activate a result to visit its source. It does not scan other files on disk.
• Outline (Ctrl+Shift+O) provides a filterable hierarchy of source symbols. Activate a row to visit it. Use the gutter's Classes & Functions dialog when you want to copy an entire definition without moving the editor.
• Command Palette (Ctrl+Shift+P) finds available commands by name or shortcut. Type part of a command name, select a result, and press Enter.
• Transpilation History (Ctrl+Alt+H) shows the latest 64 conversion summaries from this application session. It does not store source copies, restore old text, or persist between launches.
• Use Make Primary in the source bundle to choose its primary module. Move Module Up/Down changes bundle order; Remove Module closes it without deleting its file.

Make the editor comfortable

Use View → Code & Editor Settings to set Python and C text sizes independently. Python starts at 14 pt and generated C at 12 pt; both allow 8–48 pt. The View menu also has Increase, Decrease, and Reset Python Text Size commands.

You can resize panes and show or hide Generated C, Source Bundle, Outline, and Transpilation Details. The application remembers layout and editor preferences. Help has its own readable text size.

Split Python View (Ctrl+\) shows two views of the active source document. They share text and Undo history, with separate viewing positions; an edit in either view updates the same file. Show Whitespace makes spaces and tabs visible without changing source. Duplicate Line or Selection, Move Line Up/Down, Toggle Comment, and Indent/Outdent operate on the affected source lines; indentation commands use four spaces.

Returning to your files

Saved files left open at exit reopen in their previous order, with the previous saved active file selected. Unsaved text is not restored, so save your work before closing. Restoration runs after the workspace appears. Missing, unreadable, non-text, or oversized files are skipped and listed in the Startup report; a read taking more than ten seconds is also skipped. Files are left unchanged, and unavailable paths remain saved for a later launch. A readable file with incomplete Python syntax can still be opened for editing.

File → Open Recent → Clear Recent Files clears the recent-file list without closing your current tabs. Closing the last tab leaves an empty workspace on the next launch.

Moving and resizing dialogs

Drag a dialog by its titlebar. Resizable dialogs can be resized at the edges and maximized or restored with their titlebar controls.

Before saving C

Review the conversion result, ensure all intended files were included, and check that the result is current. Save the Python alongside the C. Follow the conversion checklist to compile and test the result.

Separate C module exports

After a fresh Typed conversion, use File → Export C Modules… for a ZIP archive of separate source/header pairs and a C interface manifest. See Separate C module exports for the complete workflow, caller example and API. Save C and the IDE Compile action continue to use single-file output.