Metadata-Version: 2.4
Name: nchantrs
Version: 0.0.1
Summary: Python module for rapidly building PySide6/PyQt5 desktop apps from YAML configuration and Python widget files, with SQLite-backed state via FxSQuiRL.
Author: Maintainers
Author-email: solubrew@solutionsbrewer.com
License: MIT
Platform: Linux
Requires-Python: >=3.10
Requires-Dist: pyside6
Requires-Dist: pyyaml
Requires-Dist: pandas
Requires-Dist: pyyaml-include>=1.3
Requires-Dist: dnspython
Requires-Dist: websockets
Requires-Dist: certifi
Requires-Dist: sqlalchemy
Requires-Dist: alembic
Requires-Dist: diskcache
Requires-Dist: requests
Requires-Dist: aiohttp
Requires-Dist: httpx
Requires-Dist: cryptography
Requires-Dist: pycryptodome
Requires-Dist: bcrypt
Requires-Dist: PyQtWebEngine
Requires-Dist: qscintilla
Requires-Dist: arrow
Requires-Dist: psutil
Requires-Dist: jsonschema
Requires-Dist: ruamel-yaml
Requires-Dist: networkx
Requires-Dist: pillow
Requires-Dist: bs4
Requires-Dist: send2trash
Requires-Dist: dill
Requires-Dist: zmq
Requires-Dist: uuid7
Requires-Dist: matplotlib
Requires-Dist: mplfinance
Requires-Dist: numpy
Requires-Dist: plotly
Requires-Dist: seaborn
Requires-Dist: wordcloud
Requires-Dist: plyer
Requires-Dist: pytest
Requires-Dist: setuptools
Requires-Dist: uuid7
Requires-Dist: black ; extra == "dev"
Requires-Dist: isort ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: pylint ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: pyright ; extra == "dev"
Requires-Dist: pytest ; extra == "test"
Requires-Dist: pytest-cov ; extra == "test"
Requires-Dist: pytest-mock ; extra == "test"
Requires-Dist: coverage ; extra == "test"
Requires-Dist: mkdocs ; extra == "docs"
Requires-Dist: mkdocs-material ; extra == "docs"
Requires-Dist: mkdocstrings ; extra == "docs"
Requires-Dist: pymdown-extensions ; extra == "docs"
Requires-Dist: ruff ; extra == "lint"
Requires-Dist: bandit ; extra == "lint"
Requires-Dist: safety ; extra == "lint"
Requires-Dist: nchantrs[dev,test,docs,lint,optional,legacy] ; extra == "all"
Provides-Extra: dev
Provides-Extra: test
Provides-Extra: docs
Provides-Extra: lint
Provides-Extra: optional
Provides-Extra: all
Description: # Nchantrs
        
        [![Python Version](https://img.shields.io/pypi/pyversions/nchantrs)](https://pypi.org/project/nchantrs/)
        [![License](https://img.shields.io/pypi/l/nchantrs)](LICENSE)
        [![Status](https://img.shields.io/pypi/status/nchantrs)](https://pypi.org/project/nchantrs/)
        [![Downloads](https://img.shields.io/pypi/dm/nchantrs)](https://pypi.org/project/nchantrs/)
        
        [![CI](https://github.com/solutionsbrewer/nchantrs/actions/workflows/ci.yml/badge.svg)](https://github.com/solutionsbrewer/nchantrs/actions)
        [![codecov](https://codecov.io/gh/solutionsbrewer/nchantrs/branch/main/graph/badge.svg)](https://codecov.io/gh/solutionsbrewer/nchantrs)
        [![Code Quality](https://img.shields.io/badge/code%20quality-95%25-success)](https://github.com/solutionsbrewer/nchantrs)
        
        [![PyPI Version](https://img.shields.io/pypi/v/nchantrs)](https://pypi.org/project/nchantrs/)
        [![Python Versions](https://img.shields.io/pypi/pyversions/nchantrs)](https://pypi.org/project/nchantrs/)
        
        Nchantrs is a Python module for rapidly creating PyQt5/PySide6 applications using YAML configuration and Python widget files. Applications are built over a SQLite backend using FxSQuiRL for database operations.
        
        ## Features
        
        - **4 Entry Points**: Choose the right architecture for your app (aberration, distortion, nchantment, flection)
        - **YAML-Based Configuration**: Define application structure, UI layouts, widgets, and database schemas
        - **Python Widget Files**: Extend functionality with custom widgets, events, and logic
        - **PyQt5/PySide6 Integration**: Cross-platform desktop GUI framework support
        - **SQLite Backend via FxSQuiRL**: Seamless database operations with one or more SQLite databases
        - **Theme System**: Built-in theming with customizable QSS templates
        - **Authentication**: Built-in password dialog and user authentication
        - **Model-View Architecture**: Clean separation of concerns (Cape/Cloak/Sigil pattern)
        
        ## Installation
        
        You can install Nchantrs via pip:
        
        ```bash
        pip install nchantrs
        ```
        
        Alternatively, clone the repository and install from source:
        
        ```bash
        git clone https://github.com/<USER_OR_ORG>/nchantrs.git
        cd nchantrs
        pip install -e .
        ```
        
        ### Requirements
        
        - Python 3.10 or higher
        - PyQt5, PyQt6, or PySide6
        - Dependencies: pyyaml, sqlalchemy, fxsquirl, kahndor, ogma, pycurity
        
        ## Quick Start
        
        ### Choose Your Entry Point
        
        Nchantrs provides 4 entry points depending on your app's complexity:
        
        | Entry Point | Use When | Backend |
        |-------------|----------|---------|
        | **aberration** | Simple dialogs, popups | None |
        | **distortion** | Single-pane tools/utilities | YAML + SQLite |
        | **nchantment** | Multi-pane office applications | SQLite + YAML |
        | **flection** | Networked/P2P applications | SQLite + YAML + P2P |
        
        ### Basic Usage
        
        ```python
        import nchantrs
        
        # Choose the right entry point for your app:
        # - aberration: Simple popup dialogs
        # - distortion: Single-pane tool apps (YAML-first)
        # - nchantment: Multi-pane office apps (SQLite-first)
        # - flection: Networked apps with P2P
        
        # For a distortion (single-pane tool) app:
        from nchantrs.dialogs.distortion import NchantdDistortion
        
        app = NchantdDistortion()
        app.initModel()    # Initialize YAML/SQLite backend
        app.initView()     # Set up UI
        app.run()          # Start application
        ```
        
        ## Usage
        
        ### Loading Configurations
        
        Nchantrs uses YAML files to define the app's UI and database interactions. A sample YAML might look like:
        
        ```yaml
        app_name: MyApp
        ui:
          main_window:
            title: Main Window
            widgets:
              - type: button
                label: Submit
                on_click: custom_handler
        database:
          schema: path/to/schema.sql
          connections:
            - name: primary
              file: database.db
        ```
        
        Use `nchantrs.load_config(yaml_path)` to parse and validate the config.
        
        ### Creating Applications
        
        ```python
        # Load config
        config = nchantrs.load_config('app.yaml')
        
        # Specify widget directory
        app = nchantrs.Application(config, widget_dir='widgets/')
        
        # Add custom widget logic from Python files
        app.register_widget('custom_widget.py')
        
        # Initialize database with FxSQuiRL
        app.init_database(config['database']['connections'][0]['file'])
        
        # Execute queries
        results = app.query('SELECT * FROM <TABLE_NAME>')
        ```
        
        ### Database Interactions
        
        Leverage FxSQuiRL for SQLite operations:
        
        ```python
        # Write data
        app.insert('INSERT INTO <TABLE_NAME> (column) VALUES (?)', ('value',))
        
        # Read data
        data = app.fetch('SELECT * FROM <TABLE_NAME> WHERE id = ?', (1,))
        ```
        
        ### Supported Frameworks
        
        - PyQt5
        - PyQt6
        - PySide2
        - PySide6
        
        ## Examples
        
        ### Example 1: Simple CRUD Application
        
        ```python
        import nchantrs
        
        config = nchantrs.load_config('crud_app.yaml')
        app = nchantrs.Application(config, widget_dir='crud_widgets/')
        app.init_database('crud.db')
        
        # Add a form widget for data entry
        app.add_form('user_form', fields=['name', 'email'])
        
        # Run with event loop
        app.run()
        ```
        
        ### Example 2: Multi-Database Dashboard
        
        ```python
        import nchantrs
        
        config = nchantrs.load_config('dashboard.yaml')
        app = nchantrs.Application(config, widget_dir='dashboard_widgets/')
        
        # Connect to multiple databases
        app.init_databases(['db1.db', 'db2.db'])
        
        # Display data in UI
        app.update_table('dashboard_table', query='SELECT * FROM metrics')
        
        app.run()
        ```
        
        ## Configuration Guide
        
        Each YAML config must include:
        
        - `app_name`: String identifier for the application
        - `ui`: Dictionary defining windows, widgets, layouts, and events
        - `database`: Details for SQLite connections, schemas, and FxSQuiRL settings
        - `widgets`: Optional mappings to Python files for custom logic
        
        For advanced customization, refer to the [docs/config-reference.md](docs/config-reference.md).
        
        ## Contributing
        
        Contributions are welcome! Please follow these steps:
        
        1. Fork the repository.
        2. Create a feature branch (`git checkout -b feature/<FEATURE_NAME>`).
        3. Commit your changes (`git commit -am 'Add some feature'`).
        4. Push to the branch (`git push origin feature/<FEATURE_NAME>`).
        5. Open a Pull Request.
        
        See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
        
        ## License
        
        This project is licensed under the <LICENSE_TYPE> License - see the [LICENSE](LICENSE) file for details.
        
        ## Acknowledgments
        
        - Built with inspiration from open-source GUI and database communities.
        - Thanks to contributors of underlying libraries like <PYQT_LIB>, FxSQuiRL.
Description-Content-Type: text/markdown
