Coverage for vibefpmgui/__init__.py: 100%
2 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-11-01 20:51 +0000
1"""A desktop GUI for the Fortran Package Manager (fpm).
3> [!NOTE]
4> These are the **API docs** for the `vibefpmgui` Python package, generated
5> with [pdoc](https://pdoc.dev) from the docstrings in the source code. They
6> describe the code; for what the app does and how to use it, see the
7> [website](https://jacobwilliams.github.io/VibeFPMGUI/) or the
8> [README](https://github.com/jacobwilliams/VibeFPMGUI#readme).
10VibeFPMGUI opens an `fpm.toml` and runs fpm's commands (build, run, test,
11update, clean) with live progress, shows the project's dependencies as an
12interactive graph, and has a built-in Fortran editor with a language server,
13linting, formatting and an AI code reviewer that runs on your own computer.
14It is written in Python with Qt (PySide6, through qtpy).
16*VibeFPMGUI is an experimental, vibe-coded project: expect rough edges.*
18## Links
20* **Website:** <https://jacobwilliams.github.io/VibeFPMGUI/>
21* **Source code and issues:** <https://github.com/jacobwilliams/VibeFPMGUI>
22* **fpm:** <https://fpm.fortran-lang.org>
23* Tools it uses: [fortls](https://fortls.fortran-lang.org) (language server),
24 [fortitude](https://fortitude.readthedocs.io) (linter),
25 [fprettify](https://github.com/fortran-lang/fprettify) (formatter),
26 [Ollama](https://ollama.com) (local AI models),
27 [pyqtgraph](https://www.pyqtgraph.org) (graph) and
28 [Pygments](https://pygments.org) (syntax highlighting).
30## Running it
32```sh
33pixi run start # reopens the last project
34pixi run start path/to/fpm.toml # or a project folder
35pixi run demo # the demo project in examples/demo
36```
38With pip (Python 3.11+): `pip install .` (add `.[fortran]` for fortls,
39fortitude and fprettify, `.[ai]` for the Ollama client), then
40`vibefpmgui [path/to/fpm.toml]`. fpm and a Fortran compiler must be on the
41`PATH`. The program starts in `vibefpmgui.main_window.main`.
43The editor tools are optional. Without fortls or fortitude their *View*
44menu item says "not found" and the feature is off; without fprettify the
45*Format* button is greyed out; AI review needs Ollama only when you start one.
47## Project structure
49**Main window**
51| Module | What it does |
52|---|---|
53| `vibefpmgui.main_window` | The window: starting it, building it in order, closing it, and `main` |
54| `vibefpmgui.window` | The window's parts, one mixin per area: panels, View menu, project, graph, editor tabs, Edit menu, language server, search, running fpm, Output, Test and Run, coverage, AI |
55| `vibefpmgui.dock_snap` | Dragging a panel's edge past its smallest size collapses it, as in VS Code |
56| `vibefpmgui.manifest` | Reading `fpm.toml` files and resolving the dependency tree (no Qt) |
57| `vibefpmgui.graph_view` | The interactive dependency graph (pyqtgraph) |
58| `vibefpmgui.project_tree` | The *Project files* tree, with fpm folder badges and `.gitignore` handling |
59| `vibefpmgui.build_outputs` | The *Build outputs* tab: what fpm keeps in `build/` |
60| `vibefpmgui.dep_updates` | *Check for Dependency Updates* (`git ls-remote`) |
61| `vibefpmgui.about` | The About window |
62| `vibefpmgui.packages` | *About → Packages…*: the environment's installed packages (`pixi list` / `conda list`) |
64**Build, test and run panels**
66| Module | What it does |
67|---|---|
68| `vibefpmgui.build_monitor` | The *Build* tab: a live table of the files fpm compiles, and compiler-message parsing |
69| `vibefpmgui.test_monitor` | The *Tests* tab: each test's progress, time and output |
70| `vibefpmgui.run_monitor` | The *Run* tab (the Tests tab with different wording) |
71| `vibefpmgui.test_runner` | The small wrapper given to `fpm test --runner` to mark where each test starts and ends |
72| `vibefpmgui.parallel_tests` | Running tests several at a time, each with its own output |
73| `vibefpmgui.fpm_args` | fpm's command line: link flags, `--runner`, the test wrapper's command |
74| `vibefpmgui.processes` | Ending a process and everything it started |
75| `vibefpmgui.ansi` | Terminal color codes in program output, shown as colors |
76| `vibefpmgui.output_links` | File locations in the output (runtime errors, backtraces, compiler messages) that open the file on a click |
77| `vibefpmgui.terminal` | The *Terminal* tab: your shell in the project's folder, with exactly the app's environment (pyte, drawn by our own widget) |
79**Editor**
81| Module | What it does |
82|---|---|
83| `vibefpmgui.editor` | The editor tab: the file (loading, saving, changes on disk), the outline, the status line |
84| `vibefpmgui.editor_language` | The tab's language-server features: hover, definitions, completion, references, rename |
85| `vibefpmgui.editor_checks` | The tab's checks: fortitude, spelling, gremlins; the compiler's, fortls's and the AI's markers |
86| `vibefpmgui.code_editor` | The text widget: keys, mouse, selections, indentation, highlights, its right-click menu |
87| `vibefpmgui.editor_gutter` | The gutter: line numbers, change bars, coverage, gremlins, markers |
88| `vibefpmgui.editor_issues` | Squiggles under issues, and the hover cards over them |
89| `vibefpmgui.multi_cursor` | Several cursors at once |
90| `vibefpmgui.hover_popup` | The editor's hover card |
91| `vibefpmgui.find_bar` | The find and replace bar |
92| `vibefpmgui.editor_shared` | What the editor's modules share: colors, delays, severities, text helpers |
93| `vibefpmgui.source_text` | Reading source files the same way everywhere: encoding, line ends, what Search skips |
94| `vibefpmgui.command_palette` | View → Command Palette…: the menus' commands, found by typing |
95| `vibefpmgui.new_project` | File → New fpm Project…: fpm new, its options chosen in a dialog |
96| `vibefpmgui.line_edits` | Toggle Line Comment, Move Line Up / Down, Sort Lines, Change Case |
97| `vibefpmgui.wrapping_tabs` | The editor's tabs on several rows (View → Editor Tabs) |
98| `vibefpmgui.console` | Console programs started without a console window flashing up (Windows); no Qt |
99| `vibefpmgui.git_status` | A repository's status and the versions of a changed file (the git program; no Qt) |
100| `vibefpmgui.git_panel` | The *Git* tab: *Diff* (the branch, the changed files, the selected one's diff) or *Stats* |
101| `vibefpmgui.git_stats` | A repository's statistics: its commits, people, branches, tags, files, size (no Qt) |
102| `vibefpmgui.git_stats_view` | The Git tab's *Stats*: tiles, the people, and their commits over time (pyqtgraph) |
103| `vibefpmgui.diff_view` | Two versions of a file side by side or unified: aligning them, folding unchanged lines |
104| `vibefpmgui.complexity` | Fortran code complexity, lizard's metrics (CCN, NLOC, tokens, parameters, length, depth); no Qt |
105| `vibefpmgui.metrics_table` | A sortable table drawn on demand (the Complexity tab's procedures and files) |
106| `vibefpmgui.complexity_panel` | The *Complexity* tab: each procedure's metrics and each file's totals |
107| `vibefpmgui.control_flow` | A procedure's control-flow graph (blocks, decisions, loops, exits) and its layered layout; no Qt |
108| `vibefpmgui.cfg_view` | Drawing a control-flow graph (pyqtgraph) |
109| `vibefpmgui.highlighter` | Pygments syntax highlighting and the *Syntax Colors* styles |
110| `vibefpmgui.themes` | *View → Theme*: the whole window's colors (System, Light, Dark and colorful ones) |
111| `vibefpmgui.lsp` | The client for the fortls language server (hover, definition, completion, references, rename) |
112| `vibefpmgui.completion` | The completion list and argument-hint popups |
113| `vibefpmgui.hover_card` | The HTML of the hover card |
114| `vibefpmgui.symbol_search` | *Go to Symbol in Project* |
115| `vibefpmgui.references_panel` | The *References* tab |
116| `vibefpmgui.result_tree` | The list of places in files shared by the *Search*, *References* and *Problems* tabs (icons, syntax-colored lines) |
117| `vibefpmgui.problems_panel` | The *Problems* tab: everything flagged in the file in the editor |
118| `vibefpmgui.project_search` | *Find in Files*: search and replace across the project and its dependencies (*Search* tab) |
119| `vibefpmgui.rename_dialog` | The *Rename Symbol* preview |
120| `vibefpmgui.lint` | Linting with fortitude |
121| `vibefpmgui.formatter` | Formatting with fprettify |
122| `vibefpmgui.spelling` | Spell checking comments and strings (pyspellchecker) |
123| `vibefpmgui.gremlins` | Finding non-ASCII and invisible characters, and drawing the gutter's gremlin |
125**AI review**
127| Module | What it does |
128|---|---|
129| `vibefpmgui.ai_review` | Prompting a local model through Ollama and parsing its findings |
130| `vibefpmgui.review_monitor` | The *Review* tab: a timeline of every review, explanation, question and edit |
131| `vibefpmgui.ai_edits` | The AI's proposed edits (search/replace blocks): finding and applying them |
132| `vibefpmgui.ai_context` | What a chat sends the model, so it fits its context window |
133| `vibefpmgui.edit_cards` | The proposed edits as cards to accept or reject |
135**Shared helpers**
137| Module | What it does |
138|---|---|
139| `vibefpmgui.icons` | Toolbar icons, symbol badges and the app icon, drawn with QPainter |
140| `vibefpmgui.coverage` | Test coverage: gcov's counts collected and read |
141| `vibefpmgui.coverage_panel` | The *Coverage* tab: totals, each file's coverage, its missed lines and functions |
142| `vibefpmgui.widgets` | Small shared widgets (a status line that never widens the window), and running a dialog |
143| `vibefpmgui.background` | Blocking calls (Format, Fix All, asking Ollama) on a pool thread, the result back in the GUI thread |
144| `vibefpmgui.compat` | Things that differ between macOS, Linux and Windows |
146## How it fits together
148* **fpm runs as a child process** (`QProcess`). Its output goes to the
149 *Output* panel and is parsed line by line for the *Build* tab. fpm only
150 prints compiler output when a compile fails, so warnings are read from
151 its per-file `.o.log` files.
152* **Tests and programs run through `vibefpmgui.test_runner`**, which fpm
153 calls for each one (`--runner`). The markers it prints tell the *Tests*
154 and *Run* tabs where each starts and ends and how it exited. For tests
155 run in parallel, it only reports each test's command line
156 (``--collect``), and `vibefpmgui.parallel_tests.ParallelTests` runs them.
157* **The editor's Fortran features use separate programs:** fortls (a
158 long-running language server, see `vibefpmgui.lsp.LspClient`), fortitude
159 and fprettify (run on the editor's text through stdin), and Ollama (over
160 HTTP, on a worker thread). None of them blocks the window.
161* **Settings** are stored with `QSettings`, some per project (keyed by the
162 manifest's path). Set the `VIBEFPMGUI_SETTINGS` environment variable to an
163 `.ini` path to use a separate settings file, e.g. for testing.
165## Development
167```sh
168pixi run ruff check . # lint the code
169pixi run test # the tests (pytest + pytest-qt; no windows appear)
170pixi run coverage # the same, with a code coverage report in web/coverage
171pixi run docs # these API docs, into web/api
172pixi run docs-serve # the same, live in the browser
173```
175The tests in `tests/` drive the real windows with
176[pytest-qt](https://pytest-qt.readthedocs.io), using Qt's offscreen platform
177(so they also run on CI machines without a display) and a settings file of
178their own (your settings are never touched). To watch them run, set
179`QT_QPA_PLATFORM=cocoa` (macOS), `xcb` (Linux) or `windows`. CI runs them on
180every push and publishes the [test coverage report](../coverage/index.html)
181(which lines of the code the tests run) next to these docs.
183Docstrings are Markdown with Google-style sections (`Args:`, `Returns:`,
184`Raises:`); a name in backticks, such as `vibefpmgui.lsp.LspClient`,
185becomes a link here.
187MIT License. The fpm logo is © 2020 fpm contributors (MIT License). The
188Fortran file icon is adapted from [vscode-icons](https://github.com/vscode-icons/vscode-icons)
189(MIT License).
190"""
192__version__ = "0.0.7"
193__docformat__ = "google" # docstrings: Markdown with Google-style sections (for pdoc)