Pavel Baksy
cbc1972797
Roster is a modern HTTP client application for GNOME, similar to Postman, built with GTK 4 and libadwaita. Features: - Send HTTP requests (GET, POST, PUT, DELETE) - Configure custom headers with add/remove functionality - Request body editor for POST/PUT/DELETE requests - View response headers and bodies in separate tabs - Track request history with JSON persistence - Load previous requests from history with confirmation dialog - Beautiful GNOME-native UI with libadwaita components - HTTPie backend for reliable HTTP communication Technical implementation: - Python 3 with GTK 4 and libadwaita 1 - Meson build system with Flatpak support - Custom widgets (HeaderRow, HistoryItem) with GObject signals - Background threading for non-blocking HTTP requests - AdwTabView for modern tabbed interface - History persistence to ~/.config/roster/history.json - Comprehensive error handling and user feedback
129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
Roster is a GNOME application written in Python using GTK 4 and libadwaita. The project follows GNOME application conventions and uses the Meson build system.
|
|
|
|
- **Application ID**: `cz.vesp.roster`
|
|
- **Build System**: Meson
|
|
- **Runtime**: GNOME Platform (org.gnome.Platform)
|
|
- **UI Framework**: GTK 4 + libadwaita (Adw)
|
|
- **Language**: Python 3
|
|
- **License**: GPL-3.0-or-later
|
|
|
|
## Build Commands
|
|
|
|
### Native Build (requires HTTPie installed on host)
|
|
|
|
```bash
|
|
# Configure the build (from project root)
|
|
meson setup builddir
|
|
|
|
# Build the project
|
|
meson compile -C builddir
|
|
|
|
# Install locally
|
|
meson install -C builddir
|
|
|
|
# Run tests
|
|
meson test -C builddir
|
|
|
|
# Clean build directory
|
|
rm -rf builddir
|
|
```
|
|
|
|
### Running the Application
|
|
|
|
**IMPORTANT**: This application requires HTTPie to make HTTP requests.
|
|
|
|
- **Flatpak (GNOME Builder)**: HTTPie is automatically included as a Flatpak module
|
|
- **Native**: Install HTTPie on your system with `pip install httpie` or `sudo dnf install httpie`
|
|
|
|
## Development with Flatpak
|
|
|
|
The project includes a Flatpak manifest (`cz.vesp.roster.json`) for building and running the application in a sandboxed environment:
|
|
|
|
```bash
|
|
# Build with GNOME Builder (recommended for GNOME apps)
|
|
# Or use flatpak-builder directly:
|
|
flatpak-builder --user --install --force-clean build-dir cz.vesp.roster.json
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Application Structure
|
|
|
|
The application follows the standard GNOME/Adwaita application pattern:
|
|
|
|
- **RosterApplication** (main.py): Singleton application class inheriting from `Adw.Application`
|
|
- Manages application lifecycle and actions (quit, about, preferences)
|
|
- Sets up keyboard shortcuts (e.g., Ctrl+Q for quit)
|
|
- Creates and presents the main window
|
|
|
|
- **RosterWindow** (window.py): Main application window inheriting from `Adw.ApplicationWindow`
|
|
- Defined as a GTK template class using `@Gtk.Template` decorator
|
|
- UI layout loaded from `window.ui` via GResources
|
|
|
|
### Resource Management
|
|
|
|
UI files are packaged into a GResource bundle:
|
|
- Defined in `src/roster.gresource.xml`
|
|
- Resource base path: `/cz/vesp/roster`
|
|
- UI files are preprocessed with `xml-stripblanks`
|
|
|
|
### File Organization
|
|
|
|
```
|
|
src/
|
|
__init__.py # Package marker
|
|
main.py # Application class and entry point
|
|
window.py # Main window class
|
|
window.ui # Main window UI definition (GTK Builder XML)
|
|
shortcuts-dialog.ui # Keyboard shortcuts dialog
|
|
roster.in # Launcher script template (configured by Meson)
|
|
roster.gresource.xml # GResource bundle definition
|
|
|
|
data/
|
|
cz.vesp.roster.desktop.in # Desktop entry (i18n template)
|
|
cz.vesp.roster.metainfo.xml.in # AppStream metadata (i18n template)
|
|
cz.vesp.roster.gschema.xml # GSettings schema
|
|
cz.vesp.roster.service.in # D-Bus service file (configured by Meson)
|
|
icons/ # Application icons
|
|
|
|
po/
|
|
# Translation files (gettext)
|
|
```
|
|
|
|
### Key Patterns
|
|
|
|
1. **UI Templates**: Window classes use `@Gtk.Template` decorator with `resource_path` pointing to `.ui` files in GResources. Child widgets are accessed via `Gtk.Template.Child()`.
|
|
|
|
2. **Actions**: Application actions are created with the `create_action()` helper method, which sets up actions and optional keyboard shortcuts.
|
|
|
|
3. **Internationalization**: Uses gettext with domain "roster". Template files (`.in`) are processed through `i18n.merge_file()` during build.
|
|
|
|
4. **Configuration Data**: Meson substitutes variables in `.in` files using `configuration_data()` (e.g., paths, version).
|
|
|
|
5. **Module Installation**: Python modules are installed to `{datadir}/roster/roster/` and the launcher script is configured with the correct Python interpreter path.
|
|
|
|
## Adding New Python Modules
|
|
|
|
When adding new `.py` files to `src/`:
|
|
1. Add the filename to `roster_sources` list in `src/meson.build`
|
|
2. Import in `main.py` or other modules as needed
|
|
|
|
## Adding New UI Files
|
|
|
|
When adding new `.ui` files:
|
|
1. Place in `src/` directory
|
|
2. Add `<file>` entry to `src/roster.gresource.xml`
|
|
3. Use `@Gtk.Template(resource_path='/cz/vesp/roster/filename.ui')` in the corresponding Python class
|
|
|
|
## GSettings Schema
|
|
|
|
Settings are defined in `data/cz.vesp.roster.gschema.xml`. After modifying:
|
|
- Schema is validated during `meson test`
|
|
- Compiled automatically during installation via `gnome.post_install()`
|