GETTING STARTED

Desktop workspace

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

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 white, read-only text box make the report easy to identify. 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.

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.

Generated C uses a normal scrollbar without the dense mapping overview strip. 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. Switching modules or refreshing syntax highlighting restores the markers for the displayed source. 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. 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.

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

Open Transpilation Details to see diagnostics and conversion details. Selecting a diagnostic highlights the affected Python. Typed conversions provide source mappings and ForgeLens highlighting to locate the corresponding C. Runtime value conversions provide source diagnostics and generated-function names; exact ForgeLens mappings are unavailable for that mode.

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.