# Riferimento API

La sezione seguente usa `autodoc` per estrarre docstring direttamente dai moduli Python principali del progetto.

## main.py

Application entry point for the warehouse desktop tool.

This module wires together the shared async database client, the global background event loop and the different Tk/CustomTkinter windows exposed by the project.

main.open_pickinglist_window(parent, db_client)

  Open the picking list window while minimizing initial flicker.

  Parameters:

    - parent (Misc)

    - db_client (AsyncMSSQLClient)

class main.Launcher

  Bases: `CTk`

  Main launcher window that exposes the available warehouse tools.

## async_msssql_query.py

Async SQL Server access layer used by the warehouse application.

The module centralizes DSN creation and exposes `AsyncMSSQLClient`, which lazily binds a SQLAlchemy async engine to the running event loop. The implementation intentionally avoids pooling because the GUI schedules work on a single shared background loop and pooled connections were a source of cross-loop errors.

async_msssql_query.make_mssql_dsn(*, server, database, user=None, password=None, driver='ODBC Driver 17 for SQL Server', trust_server_certificate=True, encrypt=None, extra_odbc_kv=None)

  Build a SQLAlchemy `mssql+aioodbc` DSN from SQL Server parameters.

  Parameters:

    - server (str)

    - database (str)

    - user (str | None)

    - password (str | None)

    - driver (str)

    - trust_server_certificate (bool)

    - encrypt (str | None)

    - extra_odbc_kv (Dict[str, str] | None)

  Return type:

    str

class async_msssql_query.AsyncMSSQLClient(dsn, *, echo=False, log=True)

  Bases: `object`

  Thin async query client for SQL Server.

  The engine is created lazily on the currently running event loop and uses `sqlalchemy.pool.NullPool` to avoid recycling connections across loops or threads.

  Parameters:

    - dsn (str)

    - echo (bool)

    - log (bool)

  async dispose()

    Dispose the engine on the loop where it was created.

  async query_json(sql, params=None, *, as_dict_rows=False)

    Execute a query and return a JSON-friendly payload.

    Parameters:

      - sql (str) – SQL statement to execute.

      - params (Dict[str, Any] | None) – Optional named parameters bound to the statement.

      - as_dict_rows (bool) – When `True` returns rows as dictionaries keyed by column name; otherwise rows are returned as lists.

    Returns:

      A dictionary containing column names, rows and elapsed execution time in milliseconds.

    Return type:

      Dict[str, Any]

  async exec(sql, params=None, *, commit=False)

    Execute a DML statement and return its row count.

    Parameters:

      - sql (str)

      - params (Dict[str, Any] | None)

      - commit (bool)

    Return type:

      int

## gestione_aree_frame_async.py

Shared Tk/async helpers used by multiple warehouse windows.

The module bundles three concerns used throughout the GUI:

- lifecycle of the shared background asyncio loop;

- a modal-like busy overlay shown during long-running tasks;

- an `AsyncRunner` that schedules coroutines and re-enters Tk safely.

gestione_aree_frame_async.get_global_loop()

  Return the shared background event loop, creating it if needed.

  Return type:

    AbstractEventLoop

gestione_aree_frame_async.stop_global_loop()

  Stop the shared event loop and release thread references.

class gestione_aree_frame_async.BusyOverlay(parent)

  Bases: `object`

  Semi-transparent overlay used to block interaction during async tasks.

  Parameters:

    parent (tk.Misc)

  show(message='Attendere...')

    Display the overlay or just update its message if already visible.

  hide()

    Dismiss the overlay and unregister resize bindings.

class gestione_aree_frame_async.AsyncRunner(widget)

  Bases: `object`

  Run awaitables on the shared loop and callback on Tk’s main thread.

  Parameters:

    widget (tk.Misc)

  run(awaitable, on_success, on_error=None, busy=None, message='Operazione in corso...')

    Schedule `awaitable` and dispatch completion callbacks in Tk.

    Parameters:

      - on_success (Callable[[Any], None])

      - on_error (Callable[[BaseException], None] | None)

      - busy (BusyOverlay | None)

      - message (str)

  close()

    No-op kept for API compatibility with older callers.

## layout_window.py

Graphical aisle layout viewer for warehouse cells and pallet occupancy.

layout_window.pct_text(p_full, p_double=None)

  Format occupancy percentages for the progress-bar labels.

  Parameters:

    - p_full (float)

    - p_double (float | None)

  Return type:

    str

class layout_window.LayoutWindow(parent, db_app)

  Bases: `CTkToplevel`

  Visualizzazione layout corsie con matrice di celle. - Ogni cella è un pulsante colorato (vuota/piena/doppia) - Etichetta su DUE righe:

  > 1. “Corsia.Colonna.Fila” (una sola riga, senza andare a capo)

  > 2. barcode UDC (primo, se presente)

  - Ricerca per barcode UDC con cambio automatico corsia + highlight cella

  - Statistiche: globale e corsia selezionata

  - Export XLSX

  Parameters:

    parent (tk.Widget)

  destroy()

    Mark the window as closed and release dynamic widgets safely.

layout_window.open_layout_window(parent, db_app)

  Open the layout window as a singleton-like child of `parent`.

## reset_corsie.py

Window used to inspect and empty an entire warehouse aisle.

The module exposes a destructive maintenance tool: it summarizes the occupancy state of a selected aisle and, after explicit confirmation, deletes matching rows from `MagazziniPallet`.

class reset_corsie.ResetCorsieWindow(parent, db_client)

  Bases: `CTkToplevel`

  Toplevel used to inspect and clear the pallets assigned to an aisle.

  refresh()

    Refresh both the summary counters and the occupied-cell list.

reset_corsie.open_reset_corsie_window(parent, db_app)

  Create, focus and return the aisle reset window.

## view_celle_multiple.py

Exploration window for cells containing more than one pallet.

class view_celle_multiple.CelleMultipleWindow(root, db_client, runner=None)

  Bases: `CTkToplevel`

  Tree-based explorer for duplicated pallet allocations.

  Parameters:

    runner (AsyncRunner | None)

  refresh_all()

    Reload both the duplication tree and the summary percentage table.

  expand_all()

    Expand all aisle roots and trigger lazy loading where needed.

  collapse_all()

    Collapse all root nodes in the duplication tree.

  export_to_xlsx()

    Export both the detailed tree and the summary table to Excel.

view_celle_multiple.open_celle_multiple_window(root, db_client, runner=None)

  Create, focus and return the duplicated-cells explorer.

  Parameters:

    - root (Tk)

    - runner (AsyncRunner | None)

## search_pallets.py

Search window for pallets, lots and product codes across the warehouse.

class search_pallets.SearchWindow(parent, db_app)

  Bases: `CTkToplevel`

  Window that searches pallets by barcode, lot or product code.

  Parameters:

    parent (tk.Widget)

search_pallets.open_search_window(parent, db_app)

  Open a singleton-like search window tied to the launcher instance.

## gestione_pickinglist.py

Picking list management window.

The module presents a master/detail UI for packing lists, supports reservation and unreservation through an async stored-procedure port and keeps rendering smooth by relying on deferred updates and lightweight progress indicators.

class gestione_pickinglist.ColSpec(title, key, width, anchor)

  Bases: `object`

  Describe one logical column rendered in a `ScrollTable`.

  Parameters:

    - title (str)

    - key (str)

    - width (int)

    - anchor (str)

  title: str
  key: str
  width: int
  anchor: str

class gestione_pickinglist.ToolbarSpinner(parent)

  Bases: `object`

  Micro-animazione leggerissima per indicare attività: mostra una label con frame: ◐ ◓ ◑ ◒ … finché è attivo.

  Parameters:

    parent (tk.Widget)

  FRAMES = ('◐', '◓', '◑', '◒')
  widget()

    Return the label widget hosting the spinner animation.

    Return type:

      CTkLabel

  start(text='')

    Start the animation and optionally show a short status message.

    Parameters:

      text (str)

  stop()

    Stop the animation and clear the label text.

class gestione_pickinglist.ScrollTable(master, columns)

  Bases: `CTkFrame`

  Parameters:

    columns (List[ ColSpec ])

  GRID_COLOR = '#D0D5DD'
  PADX_L = 8
  PADX_R = 8
  PADY = 2
  clear_rows()

    Remove all rendered body rows.

  add_row(values, row_index, anchors=None, checkbox_builder=None)

    Append one row to the table body.

    Parameters:

      - values (List[str])

      - row_index (int)

      - anchors (List[str] | None)

      - checkbox_builder (Callable[[Widget], CTkCheckBox] | None)

class gestione_pickinglist.PLRow(pl, on_check)

  Bases: `object`

  State holder for one picking list row and its selection checkbox.

  Parameters:

    pl (Dict[str, Any])

  is_checked()

    Return whether the row is currently selected.

    Return type:

      bool

  set_checked(val)

    Programmatically update the checkbox state.

    Parameters:

      val (bool)

  build_checkbox(parent)

    Create the checkbox widget bound to this row model.

    Return type:

      CTkCheckBox

class gestione_pickinglist.GestionePickingListFrame(master, *, db_client=None, conn_str=None)

  Bases: `CTkFrame`

  rows_models: list[ PLRow ]
  on_row_checked(model, is_checked)

    Handle row selection changes and refresh the detail section.

    Parameters:

      - model (PLRow)

      - is_checked (bool)

  reload_from_db(first=False)

    Load or reload the picking list summary table from the database.

    Parameters:

      first (bool)

  on_prenota()

    Reserve the selected picking list.

  on_sprenota()

    Unreserve the selected picking list.

  on_export()

    Placeholder for a future export implementation.

gestione_pickinglist.create_frame(parent, *, db_client=None, conn_str=None)

  Factory used by the launcher to build the picking list frame.

  Return type:

    GestionePickingListFrame

## prenota_sprenota_sql.py

Async port of the packing list reservation stored procedure.

class prenota_sprenota_sql.SPResult(rc=0, message='', id_result=None)

  Bases: `object`

  Container returned by the async stored-procedure port.

  Parameters:

    - rc (int)

    - message (str | None)

    - id_result (int | None)

  rc: int = 0
  message: str | None = ''
  id_result: int | None = None

async prenota_sprenota_sql.sp_xExePackingListPallet_async(db, IDOperatore, Documento)

  Toggle the reservation state of all cells belonging to a packing list.

  The implementation mirrors the original SQL stored procedure while using the shared async DB client already managed by the application.

  Parameters:

    - IDOperatore (int)

    - Documento (str)

  Return type:

    SPResult