ea10dae1e8
Replace HTTPie subprocess calls with native libsoup3 async API. This eliminates external dependencies and uses GNOME-standard async patterns. Changes: - Rewrite http_client.py to use libsoup3 Session and Message APIs - Replace threading with GLib async callbacks in window.py - Remove HTTPie dependency from Flatpak manifest - Update documentation to reflect libsoup3 usage Benefits: - No external dependencies (HTTPie removed) - Native GLib async integration (no threading complexity) - Better performance with connection pooling and HTTP/2 support - Cleaner codebase following GNOME development patterns
126 lines
4.2 KiB
Markdown
126 lines
4.2 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
|
|
|
|
```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
|
|
|
|
The application uses **libsoup3** (from GNOME Platform) for HTTP requests - no external dependencies required.
|
|
|
|
## 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()`
|