jdxi_editor.midi.data.programs.database
=======================================

.. py:module:: jdxi_editor.midi.data.programs.database

.. autoapi-nested-parse::

   SQLite database module for storing JD-Xi user programs.

   This module provides a more robust storage solution than JSON files,
   with proper transactions, better querying, and reduced race conditions.



Attributes
----------

.. autoapisummary::

   jdxi_editor.midi.data.programs.database._db_instance


Classes
-------

.. autoapisummary::

   jdxi_editor.midi.data.programs.database.ProgramDatabase


Functions
---------

.. autoapisummary::

   jdxi_editor.midi.data.programs.database.get_database


Module Contents
---------------

.. py:class:: ProgramDatabase(db_path: Optional[pathlib.Path] = None)

   SQLite database for storing user programs.


   .. py:attribute:: db_path
      :value: None



   .. py:method:: _init_database() -> None

      Initialize the database schema if it doesn't exist.



   .. py:method:: _get_connection()

      Get a database connection with proper error handling.



   .. py:method:: add_or_replace_program(program: jdxi_editor.jdxi.program.program.JDXiProgram) -> bool

      Add or replace a program in the database.

      :param program: JDXiProgram to add or replace
      :return: True if successful, False otherwise



   .. py:method:: get_program_by_id(program_id: str) -> Optional[jdxi_editor.jdxi.program.program.JDXiProgram]

      Get a program by its ID.

      :param program_id: Program ID (e.g., "E01", "F32")
      :return: JDXiProgram if found, None otherwise



   .. py:method:: get_all_programs() -> List[jdxi_editor.jdxi.program.program.JDXiProgram]

      Get all programs from the database.

      :return: List of JDXiProgram objects



   .. py:method:: get_programs_by_bank(bank: str) -> List[jdxi_editor.jdxi.program.program.JDXiProgram]

      Get all programs for a specific bank.

      :param bank: Bank letter (e.g., "E", "F", "G", "H")
      :return: List of JDXiProgram objects



   .. py:method:: delete_program(program_id: str) -> bool

      Delete a program from the database.

      :param program_id: Program ID to delete
      :return: True if deleted, False otherwise



   .. py:method:: _row_to_program(row: sqlite3.Row) -> jdxi_editor.jdxi.program.program.JDXiProgram

      Convert a database row to a JDXiProgram object.



   .. py:method:: create_playlist(name: str, description: str = None) -> Optional[int]

      Create a new playlist.

      :param name: Playlist name (must be unique)
      :param description: Optional description
      :return: Playlist ID if successful, None otherwise



   .. py:method:: get_all_playlists() -> List[Dict]

      Get all playlists.

      :return: List of playlist dictionaries



   .. py:method:: _get_playlist_program_count(playlist_id: int) -> int

      Get the number of programs in a playlist.



   .. py:method:: get_playlist_by_id(playlist_id: int) -> Optional[Dict]

      Get a playlist by ID.

      :param playlist_id: Playlist ID
      :return: Playlist dictionary if found, None otherwise



   .. py:method:: update_playlist(playlist_id: int, name: str = None, description: str = None) -> bool

      Update a playlist.

      :param playlist_id: Playlist ID
      :param name: New name (optional)
      :param description: New description (optional)
      :return: True if successful, False otherwise



   .. py:method:: delete_playlist(playlist_id: int) -> bool

      Delete a playlist and all its items.

      :param playlist_id: Playlist ID
      :return: True if successful, False otherwise



   .. py:method:: add_program_to_playlist(playlist_id: int, program_id: str, position: int = None) -> bool

      Add a program to a playlist.

      :param playlist_id: Playlist ID
      :param program_id: Program ID (e.g., "E01")
      :param position: Position in playlist (optional, will append if not provided)
      :return: True if successful, False otherwise



   .. py:method:: remove_program_from_playlist(playlist_id: int, program_id: str) -> bool

      Remove a program from a playlist.

      :param playlist_id: Playlist ID
      :param program_id: Program ID
      :return: True if successful, False otherwise



   .. py:method:: get_playlist_programs(playlist_id: int) -> List[Dict]

      Get all programs in a playlist with their MIDI file paths, ordered by position.

      :param playlist_id: Playlist ID
      :return: List of dictionaries with 'program' (JDXiProgram) and 'midi_file_path' (str)



   .. py:method:: update_playlist_item_midi_file(playlist_id: int, program_id: str, midi_file_path: str) -> bool

      Update the MIDI file path for a playlist item.

      :param playlist_id: Playlist ID
      :param program_id: Program ID
      :param midi_file_path: Path to MIDI file (or None to clear)
      :return: True if successful, False otherwise



   .. py:method:: update_playlist_item_cheat_preset(playlist_id: int, program_id: str, cheat_preset_id: Optional[str] = None) -> bool

      Update the cheat preset ID for a playlist item.

      :param playlist_id: Playlist ID
      :param program_id: Program ID
      :param cheat_preset_id: Cheat preset ID (e.g., "113") or None to clear
      :return: True if updated, False otherwise



   .. py:method:: migrate_from_json(json_file: pathlib.Path) -> int

      Migrate programs from JSON file to SQLite database.

      :param json_file: Path to JSON file
      :return: Number of programs migrated



.. py:data:: _db_instance
   :type:  Optional[ProgramDatabase]
   :value: None


.. py:function:: get_database() -> ProgramDatabase

   Get the global database instance.