### Install PySide6 Settings via pip

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Install the library using pip. This is the recommended method for most users.

```bash
pip install pyside6-settings
```

--------------------------------

### Install PySide6 Settings from Source

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Install the library from its source code. This is useful for development or when needing the latest changes.

```bash
git clone https://github.com/yourusername/pyside6-settings.git
cd pyside6-settings
pip install -e .
```

--------------------------------

### Complete Editor Settings Example

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

This snippet shows a full implementation of `BaseSettings` for an editor application. It includes various field types like strings, booleans, integers, lists, and paths, with Pydantic validation and PySide6 widget integration. Load settings from a JSON file and display them in a form.

```python
from pathlib import Path
from typing import List, Optional
from pydantic import Field
from pyside6_settings import BaseSettings, Field
from PySide6.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QWidget, QPushButton

class EditorSettings(BaseSettings):
    # General Settings
    window_title: str = Field(
        default="My Editor",
        title="Window Title",
        group="General"
    )
    
    auto_save: bool = Field(
        default=True,
        title="Auto Save",
        description="Automatically save files",
        group="General"
    )
    
    # Editor Settings
    font_family: str = Field(
        default="Monospace",
        title="Font Family",
        choices=["Monospace", "Arial", "Times New Roman"],
        group="Editor"
    )
    
    font_size: int = Field(
        default=12,
        ge=8,
        le=32,
        title="Font Size",
        group="Editor"
    )
    
    tab_size: int = Field(
        default=4,
        ge=1,
        le=8,
        title="Tab Size",
        group="Editor"
    )
    
    # Paths
    workspace: Path = Field(
        default=Path.home(),
        title="Workspace Directory",
        fs_mode="directory",
        group="Paths"
    )
    
    recent_files: List[str] = Field(
        default_factory=list,
        title="Recent Files",
        widget="tags",
        group="Paths"
    )

def main():
    app = QApplication([])
    
    # Load settings
    settings = EditorSettings.load("editor_config.json")
    
    # Create main window
    window = QMainWindow()
    window.setWindowTitle("Editor Settings")
    
    # Create central widget with settings form
    central = QWidget()
    layout = QVBoxLayout(central)
    
    # Add settings form
    settings_form = settings.create_form()
    layout.addWidget(settings_form)
    
    # Add close button
    close_btn = QPushButton("Close")
    close_btn.clicked.connect(window.close)
    layout.addWidget(close_btn)
    
    window.setCentralWidget(central)
    window.resize(600, 500)
    window.show()
    
    app.exec()

if __name__ == "__main__":
    main()

```

--------------------------------

### Grouped Settings in PySide6 Settings

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Organizes settings into collapsible groups using the 'group' parameter in Field. This example shows 'Account' and 'Appearance' groups.

```python
from pydantic import Field
from pyside6_settings import BaseSettings, WidgetMetadata

class MySettings(BaseSettings):
    # Account Group
    username: str = Field(
        default="",
        title="Username",
        group="Account",
        description="Your account username"
    )
    
    password: str = Field(
        default="",
        title="Password",
        widget="password",
        group="Account"
    )
    
    # Appearance Group
    font_size: int = Field(
        default=12,
        ge=8,
        le=32,
        title="Font Size",
        group="Appearance"
    )
    
    theme: str = Field(
        default="dark",
        title="Color Theme",
        choices=["light", "dark", "high-contrast"],
        group="Appearance"
    )

settings = MySettings.load("config.json")
form = settings.create_form()  # Creates form with "Account" and "Appearance" groups
```

--------------------------------

### Get Individual Widgets for Custom Layouts

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Retrieve specific field widgets from loaded settings for use in custom layouts. You can get widgets with or without labels, or an entire group as a `QGroupBox`.

```python
settings = MySettings.load("config.json")

# Get widget without label
username_widget = settings.get_widget("username", with_label=False)

# Get widget with label (in QFormLayout)
username_field = settings.get_widget("username", with_label=True)

# Get entire group as QGroupBox
account_group = settings.get_group("Account")
```

--------------------------------

### Override Widget Type with Field Metadata

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Use the `widget` parameter in `WidgetMetadata` to specify a custom widget for a field. This example forces a textarea for a string field.

```python
description: str = Field(
    default="",
    widget="textarea"
)
```

--------------------------------

### Load Settings in Different Formats

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Demonstrates loading configuration settings from files with different extensions. The format is automatically detected.

```python
# Use different formats
json_settings = MySettings.load("config.json")
yaml_settings = MySettings.load("config.yaml")
toml_settings = MySettings.load("config.toml")
```

--------------------------------

### Implement and Register Custom Config Loader

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Shows how to create a custom configuration loader by inheriting from BaseConfigLoader and registering it for a new file extension.

```python
from pyside6_settings.loaders import BaseConfigLoader

class CustomLoader(BaseConfigLoader):
    def load(self) -> dict:
        # Your loading logic
        pass
    
    def save(self, data: dict) -> None:
        # Your saving logic
        pass

# Register the loader
from pyside6_settings import DEFAULT_LOADERS
DEFAULT_LOADERS[".custom"] = CustomLoader
```

--------------------------------

### Basic Settings Management with PySide6 Settings

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Demonstrates basic usage of BaseSettings for defining application settings with automatic UI generation and data binding. Settings are loaded from and saved to a JSON file.

```python
from pathlib import Path
from pyside6_settings import BaseSettings, Field
from PySide6.QtWidgets import QApplication, QMainWindow

class AppSettings(BaseSettings):
    # Basic fields with automatic widget generation
    username: str = Field(default="user", description="Your username")
    age: int = Field(default=25, ge=0, le=150, description="Your age")
    enabled: bool = Field(default=True, description="Enable feature")
    
    # Field with choices (creates QComboBox)
    theme: str = Field(
        default="dark",
        title="Theme",
        choices=["light", "dark", "auto"]
    )

# Create Qt application
app = QApplication([])

# Load settings from file (creates if doesn't exist)
settings = AppSettings.load("config.json")

# Create main window with settings form
window = QMainWindow()
window.setCentralWidget(settings.create_form())
window.setWindowTitle("Application Settings")
window.show()

# Changes are automatically saved to config.json
settings.username = "new_user"  # Auto-saved!

app.exec()
```

--------------------------------

### BaseSettings Instance Methods

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Methods for creating and retrieving widgets and groups within the settings form.

```APIDOC
## BaseSettings.create_form

### Description
Creates a complete settings form widget.

### Method
`create_form(parent: QWidget | None = None) -> QWidget`

### Parameters
#### Path Parameters
- **parent** (QWidget | None) - Optional - The parent widget for the form.

### Response
#### Success Response
- **QWidget** - The created settings form widget.
```

```APIDOC
## BaseSettings.get_widget

### Description
Retrieves a specific widget associated with a field name.

### Method
`get_widget(field_name: str, with_label: bool = True) -> QWidget`

### Parameters
#### Path Parameters
- **field_name** (str) - Required - The name of the field whose widget is to be retrieved.
- **with_label** (bool) - Optional - Whether to include the label with the widget (default: True).

### Response
#### Success Response
- **QWidget** - The widget associated with the specified field name.
```

```APIDOC
## BaseSettings.get_group

### Description
Retrieves a QGroupBox for a specific group name.

### Method
`get_group(group_name: str) -> QGroupBox`

### Parameters
#### Path Parameters
- **group_name** (str) - Required - The name of the group whose QGroupBox is to be retrieved.

### Response
#### Success Response
- **QGroupBox** - The QGroupBox for the specified group name.
```

--------------------------------

### Run PySide6 Settings Tests with Coverage

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Run the PySide6-Settings test suite and generate an HTML coverage report.

```bash
pytest tests/ --cov=pyside6_settings --cov-report=html
```

--------------------------------

### Run PySide6 Settings Tests

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Execute the test suite for the PySide6-Settings project.

```bash
pytest tests/ -v
```

--------------------------------

### BaseSettings Class Methods

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Provides methods for loading settings and interacting with the settings form.

```APIDOC
## BaseSettings.load

### Description
Loads settings from a specified configuration file.

### Method
`load(config_file: str | Path) -> Self`

### Parameters
#### Path Parameters
- **config_file** (str | Path) - Required - The path to the configuration file to load.

### Response
#### Success Response
- **Self** - Returns an instance of the settings class.
```

--------------------------------

### Settings Validation with Pydantic

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Illustrates how to use Pydantic for validating settings, including type checking and custom validation logic for fields like email and port range.

```python
from pydantic import Field, field_validator

class ValidatedSettings(BaseSettings):
    email: str = Field(default="")
    port: int = Field(default=8080, ge=1, le=65535)
    
    @field_validator("email")
    @classmethod
    def validate_email(cls, v):
        if v and "@" not in v:
            raise ValueError("Invalid email address")
        return v

settings = ValidatedSettings.load("config.json")
settings.email = "invalid"  # Raises ValidationError
```

--------------------------------

### Advanced Widget Types in PySide6 Settings

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Demonstrates the use of advanced widget types for settings, including file/directory browsers, tag inputs, multi-line text areas, password fields, and numeric fields with constraints.

```python
from pathlib import Path
from typing import List
from pydantic import Field
from pyside6_settings import BaseSettings, WidgetMetadata

class AdvancedSettings(BaseSettings):
    # File/Directory Browser
    project_path: Path = Field(
        default=Path("."),
        title="Project Directory",
        s_mode="directory"
    )
    
    config_file: Path = Field(
        default=Path("config.ini"),
        title="Config File",
        fs_mode="file"
    )
    
    # Tag/List Input
    tags: List[str] = Field(
        default_factory=list,
        title="Tags",
        widget="tags"
    )
    
    # Multi-line Text
    description: str = Field(
        default="",
        title="Description",
        widget="textarea"
    )
    
    # Password Field
    api_key: str = Field(
        default="",
        title="API Key",
        widget="password"
    )
    
    # Numeric with Constraints
    timeout: float = Field(
        default=30.0,
        ge=1.0,
        le=300.0,
        title="Timeout (seconds)"
    )

settings = AdvancedSettings.load("advanced.json")
```

--------------------------------

### WidgetMetadata Properties

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Configuration options for controlling widget behavior and appearance.

```APIDOC
## WidgetMetadata

### Description
Configuration for widget behavior and appearance.

### Properties
- **title** (str) - Display label for the field.
- **description** (str) - Tooltip text.
- **group** (str) - Group name (default: "General").
- **widget** (str) - Force specific widget type.
- **choices** (List[str]) - Options for dropdown (creates QComboBox).
- **fs_mode** (str) - File system mode: "file" or "directory".
```

--------------------------------

### Programmatic Access to Settings

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Interact with settings as if they were normal Python objects. Read values directly by attribute access and modify them, which automatically saves the changes.

```python
settings = MySettings.load("config.json")

# Read values
print(settings.username)
print(settings.theme)

# Modify values (automatically saved)
settings.username = "new_user"
settings.theme = "light"

# Access all fields
for field_name in settings.__pydantic_fields__:
    value = getattr(settings, field_name)
    print(f"{field_name}: {value}")
```

--------------------------------

### Exclude Fields from UI or Serialization

Source: https://github.com/astralmortem/pyside6-settings/blob/main/README.md

Demonstrates how to use Pydantic's `Field` to exclude certain fields from UI display or serialization, or hide them specifically from the UI.

```python
internal_value: str = Field(default="secret", exclude=True)

# Or hide from UI only
hidden_field: str = Field(
    default="value",
    widget="hidden"
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.