# cjm-fasthtml-settings
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
## Install
``` bash
pip install cjm_fasthtml_settings
```
## Project Structure
nbs/
├── components/ (3)
│ ├── dashboard.ipynb # Settings dashboard layout components
│ ├── forms.ipynb # Form generation components for settings interfaces
│ └── sidebar.ipynb # Navigation menu components for settings sidebar
├── core/ (5)
│ ├── config.ipynb # Configuration constants, directory management, and base application schema
│ ├── html_ids.ipynb # Centralized HTML ID constants for settings components
│ ├── schema_group.ipynb # Grouping related configuration schemas for better organization
│ ├── schemas.ipynb # Schema registry and management for settings
│ └── utils.ipynb # Configuration loading, saving, and conversion utilities
├── plugins.ipynb # Optional plugin integration for extensible settings systems
└── routes.ipynb # FastHTML route handlers for settings interface
Total: 10 notebooks across 2 directories
## Module Dependencies
``` mermaid
graph LR
components_dashboard[components.dashboard<br/>Dashboard]
components_forms[components.forms<br/>Forms]
components_sidebar[components.sidebar<br/>Sidebar]
core_config[core.config<br/>Config]
core_html_ids[core.html_ids<br/>HTML IDs]
core_schema_group[core.schema_group<br/>Schema Group]
core_schemas[core.schemas<br/>Schemas]
core_utils[core.utils<br/>Utils]
plugins[plugins<br/>Plugins]
routes[routes<br/>Routes]
components_dashboard --> core_config
components_dashboard --> components_sidebar
components_dashboard --> core_utils
components_dashboard --> core_html_ids
components_dashboard --> components_forms
components_forms --> core_config
components_forms --> core_utils
components_forms --> core_html_ids
components_sidebar --> core_schemas
components_sidebar --> core_config
components_sidebar --> core_html_ids
core_schemas --> core_schemas
core_schemas --> core_config
core_schemas --> core_schema_group
core_utils --> core_config
routes --> core_utils
routes --> core_config
routes --> components_sidebar
routes --> routes
routes --> core_schemas
routes --> core_html_ids
routes --> components_dashboard
routes --> components_forms
```
*23 cross-module dependencies detected*
## CLI Reference
No CLI commands found in this project.
## Module Overview
Detailed documentation for each module in the project:
### Config (`config.ipynb`)
> Configuration constants, directory management, and base application
> schema
#### Import
``` python
from cjm_fasthtml_settings.core.config import (
DEFAULT_CONFIG_DIR,
get_app_config_schema
)
```
#### Functions
``` python
def get_app_config_schema(
app_title: str = "FastHTML Application", # Default application title
config_dir: str = "configs", # Default configuration directory
server_port: int = 5000, # Default server port
themes_enum: Optional[List[str]] = None, # Optional list of theme values
themes_enum_names: Optional[List[str]] = None, # Optional list of theme display names
default_theme: Optional[str] = None, # Default theme value
include_theme: bool = True, # Whether to include theme selection
**extra_properties # Additional custom properties to add to the schema
) -> Dict[str, Any]: # JSON Schema for application configuration
"Generate a customizable application configuration schema."
```
#### Variables
``` python
DEFAULT_CONFIG_DIR
```
### Dashboard (`dashboard.ipynb`)
> Settings dashboard layout components
#### Import
``` python
from cjm_fasthtml_settings.components.dashboard import (
create_form_skeleton,
render_schema_settings_content,
settings_content
)
```
#### Functions
``` python
def create_form_skeleton(
schema_id: str, # The schema ID for the settings
hx_get_url: str # URL to fetch the actual form content
) -> FT: # Div element with loading trigger
"Create a loading skeleton for the settings form that loads asynchronously."
```
``` python
def render_schema_settings_content(
schema: Dict, # JSON schema for the settings
config_dir: Optional[Path] = None # Config directory path
) -> FT: # Settings form container
"Render settings content for a schema-based configuration."
```
``` python
def settings_content(
request, # FastHTML request object
schema: Dict, # Schema to display
schemas: Dict, # All registered schemas for sidebar
config_dir: Optional[Path] = None, # Config directory
menu_section_title: str = "Settings", # Sidebar section title
plugin_registry: Optional[Any] = None # Optional plugin registry
) -> FT: # Settings content layout
"Return settings content with sidebar and form."
```
### Forms (`forms.ipynb`)
> Form generation components for settings interfaces
#### Import
``` python
from cjm_fasthtml_settings.components.forms import (
create_settings_form,
create_settings_form_container
)
```
#### Functions
``` python
def create_settings_form(
schema: Dict[str, Any], # JSON schema for the form
values: Dict[str, Any], # Current values for the form fields
post_url: str, # URL for form submission
reset_url: str # URL for resetting form to defaults
) -> FT: # Form element with settings and action buttons
"Create a settings form with action buttons."
```
``` python
def create_settings_form_container(
schema: Dict[str, Any], # JSON schema for the form
values: Dict[str, Any], # Current values for the form fields
post_url: str, # URL for form submission
reset_url: str, # URL for resetting form to defaults
alert_message: Optional[Any] = None, # Optional alert element to display
use_alert_container: bool = False # If True, add empty alert-container div
) -> FT: # Div containing the alert (if any) and the settings form
"Create a container with optional alert and settings form."
```
### HTML IDs (`html_ids.ipynb`)
> Centralized HTML ID constants for settings components
#### Import
``` python
from cjm_fasthtml_settings.core.html_ids import (
SettingsHtmlIds
)
```
#### Classes
``` python
class SettingsHtmlIds(AppHtmlIds):
"HTML ID constants for settings components."
def menu_item(
name: str # Settings name
) -> str: # Menu item ID
"Generate a menu item ID for a given settings name."
```
### Plugins (`plugins.ipynb`)
> Optional plugin integration for extensible settings systems
#### Import
``` python
from cjm_fasthtml_settings.plugins import (
PluginRegistryProtocol
)
```
#### Classes
``` python
@runtime_checkable
class PluginRegistryProtocol(Protocol):
"Protocol that plugin registries should implement."
def get_plugin(
self,
unique_id: str # Plugin unique ID
) -> Optional[PluginMetadata]: # Plugin metadata or None
"Get plugin metadata by unique ID."
def get_plugins_by_category(
self,
category: str # Category name
) -> list[PluginMetadata]: # List of plugins in category
"Get all plugins in a category."
def get_categories_with_plugins(
self
) -> list[str]: # List of category names
"Get all categories that have registered plugins."
def load_plugin_config(
self,
unique_id: str # Plugin unique ID
) -> Dict[str, Any]: # Loaded configuration
"Load saved configuration for a plugin."
def save_plugin_config(
self,
unique_id: str, # Plugin unique ID
config: Dict[str, Any] # Configuration to save
) -> bool: # True if save succeeded
"Save configuration for a plugin."
```
### Routes (`routes.ipynb`)
> FastHTML route handlers for settings interface
#### Import
``` python
from cjm_fasthtml_settings.routes import (
config,
settings_ar,
RoutesConfig,
configure_settings,
index,
load_form,
save,
reset,
plugin_reset,
plugin_save,
plugin
)
```
#### Functions
```` python
def configure_settings(
config_dir: Path = None, # Directory for storing configuration files
wrap_with_layout: Callable = None, # Function to wrap full page content with app layout
plugin_registry = None, # Optional plugin registry (must implement PluginRegistryProtocol)
default_schema: str = "general", # Default schema to display
menu_section_title: str = "Settings" # Title for the settings menu section
) -> RoutesConfig: # Configured RoutesConfig instance
"""
Configure the settings system with a single function call.
This is a convenience function that sets all configuration options at once,
providing a cleaner alternative to setting config attributes individually.
Example:
```python
from cjm_fasthtml_settings.routes import configure_settings, settings_ar
from pathlib import Path
configure_settings(
config_dir=Path("my_configs"),
wrap_with_layout=my_layout_function,
plugin_registry=my_plugin_registry,
default_schema="general",
menu_section_title="App Settings"
)
# Now add the router to your app
settings_ar.to_app(app)
```
"""
````
``` python
def _resolve_schema(
id: str # Schema ID
) -> tuple: # (schema, error_message)
"Resolve schema from ID using the registry."
```
``` python
def _handle_htmx_request(
request, # FastHTML request object
content_fn: Callable, # Function to generate content
*args, # Positional arguments for content_fn
**kwargs # Keyword arguments for content_fn
) -> FT: # Response content
"Handle HTMX vs full page response pattern."
```
``` python
def _create_settings_response(
schema: Dict[str, Any], # Schema dictionary
values: Dict[str, Any], # Form values
save_url: str, # URL for saving
reset_url: str, # URL for resetting
alert_msg, # Alert message element
sidebar_id: str # Active sidebar ID
) -> FT: # Settings form with sidebar
"Create standardized settings form response with sidebar."
```
``` python
@settings_ar
def index(
request, # FastHTML request object
id: str = None # Schema ID to display (defaults to config.default_schema)
) -> FT: # Settings page content
"Main settings page."
```
``` python
@settings_ar
def load_form(
id: str = None # Schema ID to load (defaults to config.default_schema)
) -> FT: # Settings form content
"Async endpoint that loads the settings form."
```
``` python
@settings_ar
async def save(
request, # FastHTML request object
id: str # Schema ID to save
) -> FT: # Response with form or error
"Save configuration handler."
```
``` python
@settings_ar
def reset(
id: str # Schema ID to reset
) -> FT: # Response with form or error
"Reset configuration to defaults handler."
```
``` python
@settings_ar
def plugin_reset(
id: str # Plugin unique ID
) -> FT: # Response with form or error
"Reset plugin configuration to defaults handler."
```
``` python
@settings_ar
async def plugin_save(
request, # FastHTML request object
id: str # Plugin unique ID
) -> FT: # Response with form or error
"Save plugin configuration handler."
```
``` python
@settings_ar
def plugin(
request, # FastHTML request object
id: str # Plugin unique ID
) -> FT: # Plugin settings page content
"Plugin settings page."
```
#### Classes
``` python
class RoutesConfig:
"Configuration for settings routes behavior."
```
### Schema Group (`schema_group.ipynb`)
> Grouping related configuration schemas for better organization
#### Import
``` python
from cjm_fasthtml_settings.core.schema_group import (
SchemaGroup
)
```
#### Classes
``` python
@dataclass
class SchemaGroup:
"A group of related configuration schemas."
name: str
title: str
schemas: Dict[str, Dict[str, Any]]
icon: Optional[Any]
default_open: bool = True
description: Optional[str]
def get_schema(
self,
schema_name: str # Schema name
) -> Optional[Dict[str, Any]]: # Schema dictionary or None
"Get a specific schema from the group by name."
def get_unique_id(
self,
schema_name: str # Schema name
) -> str: # Unique ID in format: {group_name}_{schema_name}
"Generate a unique ID for a schema within this group."
def has_configured_schemas(
self,
config_dir: Path # Directory where config files are stored
) -> bool: # True if any schema in group has saved config
"Check if any schemas in this group have saved configurations."
def get_configured_schemas(
self,
config_dir: Path # Directory where config files are stored
) -> list: # List of schema names that have saved configs
"Get list of configured schema names in this group."
```
### Schemas (`schemas.ipynb`)
> Schema registry and management for settings
#### Import
``` python
from cjm_fasthtml_settings.core.schemas import (
registry,
SettingsRegistry
)
```
#### Classes
``` python
class SettingsRegistry:
def __init__(self):
self._schemas: Dict[str, Union[Dict[str, Any], 'SchemaGroup']] = {}
"Registry for managing settings schemas and schema groups."
def __init__(self):
self._schemas: Dict[str, Union[Dict[str, Any], 'SchemaGroup']] = {}
def register(
self,
schema: Union[Dict[str, Any], 'SchemaGroup'], # Schema or SchemaGroup to register
name: Optional[str] = None # Optional name override
)
"Register a settings schema or schema group."
def get(
self,
name: str # Name of the schema/group to retrieve
) -> Optional[Union[Dict[str, Any], 'SchemaGroup']]: # The schema/group, or None if not found
"Get a registered schema or group by name."
def list_schemas(
self
) -> list: # List of registered schema/group names
"List all registered schema and group names."
def get_all(
self
) -> Dict[str, Union[Dict[str, Any], 'SchemaGroup']]: # All schemas and groups
"Get all registered schemas and groups."
def resolve_schema(
self,
id: str # Schema ID (can be 'name' or 'group_schema' format)
) -> tuple: # (schema_dict, error_message)
"Resolve a schema ID to a schema dictionary."
```
### Sidebar (`sidebar.ipynb`)
> Navigation menu components for settings sidebar
#### Import
``` python
from cjm_fasthtml_settings.components.sidebar import (
create_sidebar_menu,
create_oob_sidebar_menu
)
```
#### Functions
``` python
def create_sidebar_menu(
schemas: Dict[str, Any], # Dictionary of schemas/groups to display in sidebar
active_schema: Optional[str] = None, # The currently active schema name
config_dir: Optional[Path] = None, # Directory where config files are stored
include_wrapper: bool = True, # Whether to include the outer wrapper div
menu_section_title: str = "Settings", # Title for the settings section
plugin_registry: Optional[Any] = None # Optional plugin registry
) -> FT: # Div or Ul element containing the sidebar menu
"Create the sidebar navigation menu with support for schema groups and plugins."
```
``` python
def create_oob_sidebar_menu(
schemas: Dict[str, Dict[str, Any]], # Dictionary of schemas
active_schema: str, # Active schema name
config_dir: Optional[Path] = None, # Config directory
menu_section_title: str = "Settings", # Menu section title
plugin_registry: Optional[Any] = None # Optional plugin registry
) -> FT: # Sidebar menu with OOB swap attribute
"Create sidebar menu with OOB swap attribute for HTMX."
```
### Utils (`utils.ipynb`)
> Configuration loading, saving, and conversion utilities
#### Import
``` python
from cjm_fasthtml_settings.core.utils import (
load_config,
save_config,
get_default_values_from_schema,
get_config_with_defaults,
convert_form_data_to_config
)
```
#### Functions
``` python
def load_config(
schema_name: str, # Name of the schema/configuration to load
config_dir: Optional[Path] = None # Directory where config files are stored
) -> Dict[str, Any]: # Loaded configuration dictionary (empty dict if file doesn't exist)
"Load saved configuration for a schema."
```
``` python
def save_config(
schema_name: str, # Name of the schema/configuration to save
config: Dict[str, Any], # Configuration dictionary to save
config_dir: Optional[Path] = None # Directory where config files are stored
) -> bool: # True if save succeeded, False otherwise
"Save configuration for a schema."
```
``` python
def get_default_values_from_schema(
schema: Dict[str, Any] # JSON Schema dictionary
) -> Dict[str, Any]: # Dictionary of default values extracted from schema
"Extract default values from a JSON schema."
```
``` python
def get_config_with_defaults(
schema_name: str, # Name of the schema (or unique_id for grouped schemas)
schema: Dict[str, Any], # JSON Schema dictionary
config_dir: Optional[Path] = None # Directory where config files are stored
) -> Dict[str, Any]: # Merged configuration with defaults and saved values
"Get configuration with defaults merged with saved values."
```
``` python
def convert_form_data_to_config(
form_data: dict, # Raw form data from request
schema: Dict[str, Any] # JSON Schema for type conversion
) -> dict: # Converted configuration dictionary
"Convert form data to configuration dict based on schema."
```
Raw data
{
"_id": null,
"home_page": "https://github.com/cj-mills/cjm-fasthtml-settings",
"name": "cjm-fasthtml-settings",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "nbdev jupyter notebook python",
"author": "Christian J. Mills",
"author_email": "9126128+cj-mills@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/73/a7/a0e4aeefc1cd8a09639d539c26ccec458effb87a27aa35cbcf25281c4853/cjm_fasthtml_settings-0.0.5.tar.gz",
"platform": null,
"description": "# cjm-fasthtml-settings\n\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n## Install\n\n``` bash\npip install cjm_fasthtml_settings\n```\n\n## Project Structure\n\n nbs/\n \u251c\u2500\u2500 components/ (3)\n \u2502 \u251c\u2500\u2500 dashboard.ipynb # Settings dashboard layout components\n \u2502 \u251c\u2500\u2500 forms.ipynb # Form generation components for settings interfaces\n \u2502 \u2514\u2500\u2500 sidebar.ipynb # Navigation menu components for settings sidebar\n \u251c\u2500\u2500 core/ (5)\n \u2502 \u251c\u2500\u2500 config.ipynb # Configuration constants, directory management, and base application schema\n \u2502 \u251c\u2500\u2500 html_ids.ipynb # Centralized HTML ID constants for settings components\n \u2502 \u251c\u2500\u2500 schema_group.ipynb # Grouping related configuration schemas for better organization\n \u2502 \u251c\u2500\u2500 schemas.ipynb # Schema registry and management for settings\n \u2502 \u2514\u2500\u2500 utils.ipynb # Configuration loading, saving, and conversion utilities\n \u251c\u2500\u2500 plugins.ipynb # Optional plugin integration for extensible settings systems\n \u2514\u2500\u2500 routes.ipynb # FastHTML route handlers for settings interface\n\nTotal: 10 notebooks across 2 directories\n\n## Module Dependencies\n\n``` mermaid\ngraph LR\n components_dashboard[components.dashboard<br/>Dashboard]\n components_forms[components.forms<br/>Forms]\n components_sidebar[components.sidebar<br/>Sidebar]\n core_config[core.config<br/>Config]\n core_html_ids[core.html_ids<br/>HTML IDs]\n core_schema_group[core.schema_group<br/>Schema Group]\n core_schemas[core.schemas<br/>Schemas]\n core_utils[core.utils<br/>Utils]\n plugins[plugins<br/>Plugins]\n routes[routes<br/>Routes]\n\n components_dashboard --> core_config\n components_dashboard --> components_sidebar\n components_dashboard --> core_utils\n components_dashboard --> core_html_ids\n components_dashboard --> components_forms\n components_forms --> core_config\n components_forms --> core_utils\n components_forms --> core_html_ids\n components_sidebar --> core_schemas\n components_sidebar --> core_config\n components_sidebar --> core_html_ids\n core_schemas --> core_schemas\n core_schemas --> core_config\n core_schemas --> core_schema_group\n core_utils --> core_config\n routes --> core_utils\n routes --> core_config\n routes --> components_sidebar\n routes --> routes\n routes --> core_schemas\n routes --> core_html_ids\n routes --> components_dashboard\n routes --> components_forms\n```\n\n*23 cross-module dependencies detected*\n\n## CLI Reference\n\nNo CLI commands found in this project.\n\n## Module Overview\n\nDetailed documentation for each module in the project:\n\n### Config (`config.ipynb`)\n\n> Configuration constants, directory management, and base application\n> schema\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.core.config import (\n DEFAULT_CONFIG_DIR,\n get_app_config_schema\n)\n```\n\n#### Functions\n\n``` python\ndef get_app_config_schema(\n app_title: str = \"FastHTML Application\", # Default application title\n config_dir: str = \"configs\", # Default configuration directory\n server_port: int = 5000, # Default server port\n themes_enum: Optional[List[str]] = None, # Optional list of theme values\n themes_enum_names: Optional[List[str]] = None, # Optional list of theme display names\n default_theme: Optional[str] = None, # Default theme value\n include_theme: bool = True, # Whether to include theme selection\n **extra_properties # Additional custom properties to add to the schema\n) -> Dict[str, Any]: # JSON Schema for application configuration\n \"Generate a customizable application configuration schema.\"\n```\n\n#### Variables\n\n``` python\nDEFAULT_CONFIG_DIR\n```\n\n### Dashboard (`dashboard.ipynb`)\n\n> Settings dashboard layout components\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.components.dashboard import (\n create_form_skeleton,\n render_schema_settings_content,\n settings_content\n)\n```\n\n#### Functions\n\n``` python\ndef create_form_skeleton(\n schema_id: str, # The schema ID for the settings\n hx_get_url: str # URL to fetch the actual form content\n) -> FT: # Div element with loading trigger\n \"Create a loading skeleton for the settings form that loads asynchronously.\"\n```\n\n``` python\ndef render_schema_settings_content(\n schema: Dict, # JSON schema for the settings\n config_dir: Optional[Path] = None # Config directory path\n) -> FT: # Settings form container\n \"Render settings content for a schema-based configuration.\"\n```\n\n``` python\ndef settings_content(\n request, # FastHTML request object\n schema: Dict, # Schema to display\n schemas: Dict, # All registered schemas for sidebar\n config_dir: Optional[Path] = None, # Config directory\n menu_section_title: str = \"Settings\", # Sidebar section title\n plugin_registry: Optional[Any] = None # Optional plugin registry\n) -> FT: # Settings content layout\n \"Return settings content with sidebar and form.\"\n```\n\n### Forms (`forms.ipynb`)\n\n> Form generation components for settings interfaces\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.components.forms import (\n create_settings_form,\n create_settings_form_container\n)\n```\n\n#### Functions\n\n``` python\ndef create_settings_form(\n schema: Dict[str, Any], # JSON schema for the form\n values: Dict[str, Any], # Current values for the form fields\n post_url: str, # URL for form submission\n reset_url: str # URL for resetting form to defaults\n) -> FT: # Form element with settings and action buttons\n \"Create a settings form with action buttons.\"\n```\n\n``` python\ndef create_settings_form_container(\n schema: Dict[str, Any], # JSON schema for the form\n values: Dict[str, Any], # Current values for the form fields\n post_url: str, # URL for form submission\n reset_url: str, # URL for resetting form to defaults\n alert_message: Optional[Any] = None, # Optional alert element to display\n use_alert_container: bool = False # If True, add empty alert-container div\n) -> FT: # Div containing the alert (if any) and the settings form\n \"Create a container with optional alert and settings form.\"\n```\n\n### HTML IDs (`html_ids.ipynb`)\n\n> Centralized HTML ID constants for settings components\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.core.html_ids import (\n SettingsHtmlIds\n)\n```\n\n#### Classes\n\n``` python\nclass SettingsHtmlIds(AppHtmlIds):\n \"HTML ID constants for settings components.\"\n \n def menu_item(\n name: str # Settings name\n ) -> str: # Menu item ID\n \"Generate a menu item ID for a given settings name.\"\n```\n\n### Plugins (`plugins.ipynb`)\n\n> Optional plugin integration for extensible settings systems\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.plugins import (\n PluginRegistryProtocol\n)\n```\n\n#### Classes\n\n``` python\n@runtime_checkable\nclass PluginRegistryProtocol(Protocol):\n \"Protocol that plugin registries should implement.\"\n \n def get_plugin(\n self, \n unique_id: str # Plugin unique ID\n ) -> Optional[PluginMetadata]: # Plugin metadata or None\n \"Get plugin metadata by unique ID.\"\n \n def get_plugins_by_category(\n self, \n category: str # Category name\n ) -> list[PluginMetadata]: # List of plugins in category\n \"Get all plugins in a category.\"\n \n def get_categories_with_plugins(\n self\n ) -> list[str]: # List of category names\n \"Get all categories that have registered plugins.\"\n \n def load_plugin_config(\n self, \n unique_id: str # Plugin unique ID\n ) -> Dict[str, Any]: # Loaded configuration\n \"Load saved configuration for a plugin.\"\n \n def save_plugin_config(\n self, \n unique_id: str, # Plugin unique ID\n config: Dict[str, Any] # Configuration to save\n ) -> bool: # True if save succeeded\n \"Save configuration for a plugin.\"\n```\n\n### Routes (`routes.ipynb`)\n\n> FastHTML route handlers for settings interface\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.routes import (\n config,\n settings_ar,\n RoutesConfig,\n configure_settings,\n index,\n load_form,\n save,\n reset,\n plugin_reset,\n plugin_save,\n plugin\n)\n```\n\n#### Functions\n\n```` python\ndef configure_settings(\n config_dir: Path = None, # Directory for storing configuration files\n wrap_with_layout: Callable = None, # Function to wrap full page content with app layout\n plugin_registry = None, # Optional plugin registry (must implement PluginRegistryProtocol)\n default_schema: str = \"general\", # Default schema to display\n menu_section_title: str = \"Settings\" # Title for the settings menu section\n) -> RoutesConfig: # Configured RoutesConfig instance\n \"\"\"\n Configure the settings system with a single function call.\n \n This is a convenience function that sets all configuration options at once,\n providing a cleaner alternative to setting config attributes individually.\n \n Example:\n ```python\n from cjm_fasthtml_settings.routes import configure_settings, settings_ar\n from pathlib import Path\n \n configure_settings(\n config_dir=Path(\"my_configs\"),\n wrap_with_layout=my_layout_function,\n plugin_registry=my_plugin_registry,\n default_schema=\"general\",\n menu_section_title=\"App Settings\"\n )\n \n # Now add the router to your app\n settings_ar.to_app(app)\n ```\n \"\"\"\n````\n\n``` python\ndef _resolve_schema(\n id: str # Schema ID\n) -> tuple: # (schema, error_message)\n \"Resolve schema from ID using the registry.\"\n```\n\n``` python\ndef _handle_htmx_request(\n request, # FastHTML request object\n content_fn: Callable, # Function to generate content\n *args, # Positional arguments for content_fn\n **kwargs # Keyword arguments for content_fn\n) -> FT: # Response content\n \"Handle HTMX vs full page response pattern.\"\n```\n\n``` python\ndef _create_settings_response(\n schema: Dict[str, Any], # Schema dictionary\n values: Dict[str, Any], # Form values\n save_url: str, # URL for saving\n reset_url: str, # URL for resetting\n alert_msg, # Alert message element\n sidebar_id: str # Active sidebar ID\n) -> FT: # Settings form with sidebar\n \"Create standardized settings form response with sidebar.\"\n```\n\n``` python\n@settings_ar\ndef index(\n request, # FastHTML request object\n id: str = None # Schema ID to display (defaults to config.default_schema)\n) -> FT: # Settings page content\n \"Main settings page.\"\n```\n\n``` python\n@settings_ar\ndef load_form(\n id: str = None # Schema ID to load (defaults to config.default_schema)\n) -> FT: # Settings form content\n \"Async endpoint that loads the settings form.\"\n```\n\n``` python\n@settings_ar\nasync def save(\n request, # FastHTML request object\n id: str # Schema ID to save\n) -> FT: # Response with form or error\n \"Save configuration handler.\"\n```\n\n``` python\n@settings_ar\ndef reset(\n id: str # Schema ID to reset\n) -> FT: # Response with form or error\n \"Reset configuration to defaults handler.\"\n```\n\n``` python\n@settings_ar\ndef plugin_reset(\n id: str # Plugin unique ID\n) -> FT: # Response with form or error\n \"Reset plugin configuration to defaults handler.\"\n```\n\n``` python\n@settings_ar\nasync def plugin_save(\n request, # FastHTML request object\n id: str # Plugin unique ID\n) -> FT: # Response with form or error\n \"Save plugin configuration handler.\"\n```\n\n``` python\n@settings_ar\ndef plugin(\n request, # FastHTML request object\n id: str # Plugin unique ID\n) -> FT: # Plugin settings page content\n \"Plugin settings page.\"\n```\n\n#### Classes\n\n``` python\nclass RoutesConfig:\n \"Configuration for settings routes behavior.\"\n```\n\n### Schema Group (`schema_group.ipynb`)\n\n> Grouping related configuration schemas for better organization\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.core.schema_group import (\n SchemaGroup\n)\n```\n\n#### Classes\n\n``` python\n@dataclass\nclass SchemaGroup:\n \"A group of related configuration schemas.\"\n \n name: str\n title: str\n schemas: Dict[str, Dict[str, Any]]\n icon: Optional[Any]\n default_open: bool = True\n description: Optional[str]\n \n def get_schema(\n self, \n schema_name: str # Schema name\n ) -> Optional[Dict[str, Any]]: # Schema dictionary or None\n \"Get a specific schema from the group by name.\"\n \n def get_unique_id(\n self, \n schema_name: str # Schema name\n ) -> str: # Unique ID in format: {group_name}_{schema_name}\n \"Generate a unique ID for a schema within this group.\"\n \n def has_configured_schemas(\n self,\n config_dir: Path # Directory where config files are stored\n ) -> bool: # True if any schema in group has saved config\n \"Check if any schemas in this group have saved configurations.\"\n \n def get_configured_schemas(\n self,\n config_dir: Path # Directory where config files are stored\n ) -> list: # List of schema names that have saved configs\n \"Get list of configured schema names in this group.\"\n```\n\n### Schemas (`schemas.ipynb`)\n\n> Schema registry and management for settings\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.core.schemas import (\n registry,\n SettingsRegistry\n)\n```\n\n#### Classes\n\n``` python\nclass SettingsRegistry:\n def __init__(self):\n self._schemas: Dict[str, Union[Dict[str, Any], 'SchemaGroup']] = {}\n \"Registry for managing settings schemas and schema groups.\"\n \n def __init__(self):\n self._schemas: Dict[str, Union[Dict[str, Any], 'SchemaGroup']] = {}\n \n def register(\n self,\n schema: Union[Dict[str, Any], 'SchemaGroup'], # Schema or SchemaGroup to register\n name: Optional[str] = None # Optional name override\n )\n \"Register a settings schema or schema group.\"\n \n def get(\n self,\n name: str # Name of the schema/group to retrieve\n ) -> Optional[Union[Dict[str, Any], 'SchemaGroup']]: # The schema/group, or None if not found\n \"Get a registered schema or group by name.\"\n \n def list_schemas(\n self\n ) -> list: # List of registered schema/group names\n \"List all registered schema and group names.\"\n \n def get_all(\n self\n ) -> Dict[str, Union[Dict[str, Any], 'SchemaGroup']]: # All schemas and groups\n \"Get all registered schemas and groups.\"\n \n def resolve_schema(\n self,\n id: str # Schema ID (can be 'name' or 'group_schema' format)\n ) -> tuple: # (schema_dict, error_message)\n \"Resolve a schema ID to a schema dictionary.\"\n```\n\n### Sidebar (`sidebar.ipynb`)\n\n> Navigation menu components for settings sidebar\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.components.sidebar import (\n create_sidebar_menu,\n create_oob_sidebar_menu\n)\n```\n\n#### Functions\n\n``` python\ndef create_sidebar_menu(\n schemas: Dict[str, Any], # Dictionary of schemas/groups to display in sidebar\n active_schema: Optional[str] = None, # The currently active schema name\n config_dir: Optional[Path] = None, # Directory where config files are stored\n include_wrapper: bool = True, # Whether to include the outer wrapper div\n menu_section_title: str = \"Settings\", # Title for the settings section\n plugin_registry: Optional[Any] = None # Optional plugin registry\n) -> FT: # Div or Ul element containing the sidebar menu\n \"Create the sidebar navigation menu with support for schema groups and plugins.\"\n```\n\n``` python\ndef create_oob_sidebar_menu(\n schemas: Dict[str, Dict[str, Any]], # Dictionary of schemas\n active_schema: str, # Active schema name\n config_dir: Optional[Path] = None, # Config directory\n menu_section_title: str = \"Settings\", # Menu section title\n plugin_registry: Optional[Any] = None # Optional plugin registry\n) -> FT: # Sidebar menu with OOB swap attribute\n \"Create sidebar menu with OOB swap attribute for HTMX.\"\n```\n\n### Utils (`utils.ipynb`)\n\n> Configuration loading, saving, and conversion utilities\n\n#### Import\n\n``` python\nfrom cjm_fasthtml_settings.core.utils import (\n load_config,\n save_config,\n get_default_values_from_schema,\n get_config_with_defaults,\n convert_form_data_to_config\n)\n```\n\n#### Functions\n\n``` python\ndef load_config(\n schema_name: str, # Name of the schema/configuration to load\n config_dir: Optional[Path] = None # Directory where config files are stored\n) -> Dict[str, Any]: # Loaded configuration dictionary (empty dict if file doesn't exist)\n \"Load saved configuration for a schema.\"\n```\n\n``` python\ndef save_config(\n schema_name: str, # Name of the schema/configuration to save\n config: Dict[str, Any], # Configuration dictionary to save\n config_dir: Optional[Path] = None # Directory where config files are stored\n) -> bool: # True if save succeeded, False otherwise\n \"Save configuration for a schema.\"\n```\n\n``` python\ndef get_default_values_from_schema(\n schema: Dict[str, Any] # JSON Schema dictionary\n) -> Dict[str, Any]: # Dictionary of default values extracted from schema\n \"Extract default values from a JSON schema.\"\n```\n\n``` python\ndef get_config_with_defaults(\n schema_name: str, # Name of the schema (or unique_id for grouped schemas)\n schema: Dict[str, Any], # JSON Schema dictionary\n config_dir: Optional[Path] = None # Directory where config files are stored\n) -> Dict[str, Any]: # Merged configuration with defaults and saved values\n \"Get configuration with defaults merged with saved values.\"\n```\n\n``` python\ndef convert_form_data_to_config(\n form_data: dict, # Raw form data from request\n schema: Dict[str, Any] # JSON Schema for type conversion\n) -> dict: # Converted configuration dictionary\n \"Convert form data to configuration dict based on schema.\"\n```\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "A drop-in schema-based configuration system for FastHTML applications with automatic UI generation, sidebar navigation, and persistent storage.",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/cj-mills/cjm-fasthtml-settings"
},
"split_keywords": [
"nbdev",
"jupyter",
"notebook",
"python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "07ce33c45e5bfbd33fe7fc348935b486f55be589810f2854598729d1182b1c56",
"md5": "a954883ca50e1aaf7c79105ae541a298",
"sha256": "43579673ef7c249c7eabf41c52c2591a37f1e39c31fdc1a40a652d0f5455de15"
},
"downloads": -1,
"filename": "cjm_fasthtml_settings-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a954883ca50e1aaf7c79105ae541a298",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 28447,
"upload_time": "2025-10-27T22:12:16",
"upload_time_iso_8601": "2025-10-27T22:12:16.073892Z",
"url": "https://files.pythonhosted.org/packages/07/ce/33c45e5bfbd33fe7fc348935b486f55be589810f2854598729d1182b1c56/cjm_fasthtml_settings-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "73a7a0e4aeefc1cd8a09639d539c26ccec458effb87a27aa35cbcf25281c4853",
"md5": "8b9e23fb36953628fb06f057cc50d7ea",
"sha256": "1bca0c1bf42311cfb0201af47be43c33a9e1e6fd97fd8ac169bd6054e831ab96"
},
"downloads": -1,
"filename": "cjm_fasthtml_settings-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "8b9e23fb36953628fb06f057cc50d7ea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 27563,
"upload_time": "2025-10-27T22:12:17",
"upload_time_iso_8601": "2025-10-27T22:12:17.293500Z",
"url": "https://files.pythonhosted.org/packages/73/a7/a0e4aeefc1cd8a09639d539c26ccec458effb87a27aa35cbcf25281c4853/cjm_fasthtml_settings-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 22:12:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cj-mills",
"github_project": "cjm-fasthtml-settings",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cjm-fasthtml-settings"
}
JSON
