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:
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:

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