TimeFeatures 2.0.0__tar.gz → 2.1.1__tar.gz

{timefeatures-2.0.0/TimeFeatures.egg-info → timefeatures-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TimeFeatures
-Version: 2.0.0
+Version: 2.1.1
 Summary: Timefeatures add-on for Orange 3 data mining software.
 Home-page: https://github.com/alervgr/Orange-TimeFeatures
 Author: Alejandro Rivas García
@@ -42,15 +42,37 @@ Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: summary
 
-Orange3 TimeFeatures
-===============
+# Orange3 TimeFeatures
 
-Timefeatures add-on for [Orange] 3 data mining software for generating synthetic data using datasets with time series, generating graphs of relationships between the generated variables and includes another widget to save the data and configuration tables in a database.
+[![PyPI version](https://img.shields.io/pypi/v/TimeFeatures)](https://pypi.org/project/TimeFeatures/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Orange3](https://img.shields.io/badge/Orange3-add--on-orange)](https://orangedatamining.com/)
+
+TimeFeatures is an add-on for [Orange] 3 data mining software for generating synthetic data using datasets with time series, generating graphs of relationships between the generated variables, and includes widgets to save and load data and configuration tables from a database.
 
 [Orange]: https://orangedatamining.com/
 
-Installation
-------------
+## Features
+
+- 🕐 **7 time-window functions** — `shift`, `sum`, `mean`, `min`, `max`, `count`, `sd` with full chunk-boundary correctness
+- 🔗 **Chained descriptors** — derived variables can reference each other; topological sort resolves the evaluation order automatically
+- 🛡️ **Secure evaluation** — expressions run in a restricted `eval` sandbox (`__builtins__` replaced, curated whitelist only)
+- 🗄️ **PostgreSQL & MySQL** — persist and reload datasets via SQLAlchemy with dialect-agnostic SQL generation
+- 📊 **Directed weighted dependency graphs** — edge weights reflect temporal window size; visualise in Network Explorer
+- ⚡ **Bulk upload performance** — pandas `DataFrame.to_sql` with chunked multi-row INSERTs
+- 💾 **Workflow persistence** — variable definitions survive save/reload without clicking Send first
+
+## Widgets
+
+| Widget | Description |
+|---|---|
+| **Time Features Constructor** | Defines new variables from existing ones using Python-style expressions and time-window functions. Supports chained descriptors with automatic topological sorting. |
+| **Variable Dependency Graph** | Builds a directed, weighted dependency graph from the variable definitions. Edge weights summarise how far back or forward in time each variable looks. |
+| **Save to DB** | Persists the resulting dataset to a SQL database (PostgreSQL or MySQL), with full SQL-injection defences, three write modes (create / overwrite / append) and an optional completion email. |
+| **Load from DB** | Lists datasets previously stored by Save to DB and pulls the chosen one back into Orange, optionally marking the class column directly so no Select Columns widget is needed. |
+
+## Installation
 
 ### Orange add-on installer
 
@@ -64,21 +86,10 @@ To install the add-on with pip use
 
     pip install TimeFeatures
 
-To install the add-on from source, run
-
-    python setup.py install
-
-To register this add-on with Orange, but keep the code in the development directory (do not copy it to 
-Python's site-packages directory), run
-
-    python setup.py develop
-
-You can also run
+To install the add-on from source in editable mode, run
 
     pip install -e .
 
-which is sometimes preferable as you can *pip uninstall* packages later.
-
 ### Anaconda
 
 If using Anaconda Python distribution, simply run
@@ -86,16 +97,18 @@ If using Anaconda Python distribution, simply run
     pip install TimeFeatures
 
 **Required Dependencies**:
+
 * numpy>=1.22.4
 * AnyQt>=0.2.0
-* Orange3>=3.34.0
 * PyQt5>=5.15.6
 * PyQtWebEngine>=5.15.6
 * scipy>=1.7.3
+* SQLAlchemy>=1.4.0
+* psycopg2-binary>=2.9.9
+* PyMySQL>=1.0.0
 * Orange3-Network>=1.8.0
 
-Usage
------
+## Usage
 
 After the installation, the widgets from this add-on are registered with Orange. To run Orange from the terminal,
 use
@@ -108,21 +121,25 @@ or
 
 New widgets are in the toolbox bar under Time-Features section.
 
-Documentation
--------------
+## Documentation
 
 The add-on includes Sphinx documentation for each widget. Orange resolves the
 local HTML pages through its internal Help panel, not through an internet URL.
 To rebuild the documentation locally, run
 
     pip install -e ".[docs]"
+    python -m sphinx -b html docs docs/build/html
+
+The bundled in-app help is pre-built under `timefeatures/help_html/`. To
+regenerate it (e.g. after editing the `.rst` files), run
+
     python -m sphinx -b html docs timefeatures/help_html
 
 Use the widget help action in Orange to open the corresponding page inside the
 Orange Help window.
 
-Workflow Example
------
+## Workflow Example
+
 This is an example of how you can use this add-on.
 
 ![Workflow](https://github.com/alervgr/Orange-TimeFeatures/blob/main/imgs/workflow.png?raw=true)

timefeatures-2.1.1/README.md

@@ -0,0 +1,101 @@
+# Orange3 TimeFeatures
+
+[![PyPI version](https://img.shields.io/pypi/v/TimeFeatures)](https://pypi.org/project/TimeFeatures/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Orange3](https://img.shields.io/badge/Orange3-add--on-orange)](https://orangedatamining.com/)
+
+TimeFeatures is an add-on for [Orange] 3 data mining software for generating synthetic data using datasets with time series, generating graphs of relationships between the generated variables, and includes widgets to save and load data and configuration tables from a database.
+
+[Orange]: https://orangedatamining.com/
+
+## Features
+
+- 🕐 **7 time-window functions** — `shift`, `sum`, `mean`, `min`, `max`, `count`, `sd` with full chunk-boundary correctness
+- 🔗 **Chained descriptors** — derived variables can reference each other; topological sort resolves the evaluation order automatically
+- 🛡️ **Secure evaluation** — expressions run in a restricted `eval` sandbox (`__builtins__` replaced, curated whitelist only)
+- 🗄️ **PostgreSQL & MySQL** — persist and reload datasets via SQLAlchemy with dialect-agnostic SQL generation
+- 📊 **Directed weighted dependency graphs** — edge weights reflect temporal window size; visualise in Network Explorer
+- ⚡ **Bulk upload performance** — pandas `DataFrame.to_sql` with chunked multi-row INSERTs
+- 💾 **Workflow persistence** — variable definitions survive save/reload without clicking Send first
+
+## Widgets
+
+| Widget | Description |
+|---|---|
+| **Time Features Constructor** | Defines new variables from existing ones using Python-style expressions and time-window functions. Supports chained descriptors with automatic topological sorting. |
+| **Variable Dependency Graph** | Builds a directed, weighted dependency graph from the variable definitions. Edge weights summarise how far back or forward in time each variable looks. |
+| **Save to DB** | Persists the resulting dataset to a SQL database (PostgreSQL or MySQL), with full SQL-injection defences, three write modes (create / overwrite / append) and an optional completion email. |
+| **Load from DB** | Lists datasets previously stored by Save to DB and pulls the chosen one back into Orange, optionally marking the class column directly so no Select Columns widget is needed. |
+
+## Installation
+
+### Orange add-on installer
+
+Install from Orange add-on installer through Options -> Add-ons.
+
+![Installation](https://github.com/alervgr/Orange-TimeFeatures/blob/main/imgs/installation.png?raw=true)
+
+### Using pip
+
+To install the add-on with pip use
+
+    pip install TimeFeatures
+
+To install the add-on from source in editable mode, run
+
+    pip install -e .
+
+### Anaconda
+
+If using Anaconda Python distribution, simply run
+
+    pip install TimeFeatures
+
+**Required Dependencies**:
+
+* numpy>=1.22.4
+* AnyQt>=0.2.0
+* PyQt5>=5.15.6
+* PyQtWebEngine>=5.15.6
+* scipy>=1.7.3
+* SQLAlchemy>=1.4.0
+* psycopg2-binary>=2.9.9
+* PyMySQL>=1.0.0
+* Orange3-Network>=1.8.0
+
+## Usage
+
+After the installation, the widgets from this add-on are registered with Orange. To run Orange from the terminal,
+use
+
+    orange-canvas
+
+or
+
+    python3 -m Orange.canvas
+
+New widgets are in the toolbox bar under Time-Features section.
+
+## Documentation
+
+The add-on includes Sphinx documentation for each widget. Orange resolves the
+local HTML pages through its internal Help panel, not through an internet URL.
+To rebuild the documentation locally, run
+
+    pip install -e ".[docs]"
+    python -m sphinx -b html docs docs/build/html
+
+The bundled in-app help is pre-built under `timefeatures/help_html/`. To
+regenerate it (e.g. after editing the `.rst` files), run
+
+    python -m sphinx -b html docs timefeatures/help_html
+
+Use the widget help action in Orange to open the corresponding page inside the
+Orange Help window.
+
+## Workflow Example
+
+This is an example of how you can use this add-on.
+
+![Workflow](https://github.com/alervgr/Orange-TimeFeatures/blob/main/imgs/workflow.png?raw=true)

{timefeatures-2.0.0 → timefeatures-2.1.1/TimeFeatures.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TimeFeatures
-Version: 2.0.0
+Version: 2.1.1
 Summary: Timefeatures add-on for Orange 3 data mining software.
 Home-page: https://github.com/alervgr/Orange-TimeFeatures
 Author: Alejandro Rivas García
@@ -42,15 +42,37 @@ Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: summary
 
-Orange3 TimeFeatures
-===============
+# Orange3 TimeFeatures
 
-Timefeatures add-on for [Orange] 3 data mining software for generating synthetic data using datasets with time series, generating graphs of relationships between the generated variables and includes another widget to save the data and configuration tables in a database.
+[![PyPI version](https://img.shields.io/pypi/v/TimeFeatures)](https://pypi.org/project/TimeFeatures/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Orange3](https://img.shields.io/badge/Orange3-add--on-orange)](https://orangedatamining.com/)
+
+TimeFeatures is an add-on for [Orange] 3 data mining software for generating synthetic data using datasets with time series, generating graphs of relationships between the generated variables, and includes widgets to save and load data and configuration tables from a database.
 
 [Orange]: https://orangedatamining.com/
 
-Installation
-------------
+## Features
+
+- 🕐 **7 time-window functions** — `shift`, `sum`, `mean`, `min`, `max`, `count`, `sd` with full chunk-boundary correctness
+- 🔗 **Chained descriptors** — derived variables can reference each other; topological sort resolves the evaluation order automatically
+- 🛡️ **Secure evaluation** — expressions run in a restricted `eval` sandbox (`__builtins__` replaced, curated whitelist only)
+- 🗄️ **PostgreSQL & MySQL** — persist and reload datasets via SQLAlchemy with dialect-agnostic SQL generation
+- 📊 **Directed weighted dependency graphs** — edge weights reflect temporal window size; visualise in Network Explorer
+- ⚡ **Bulk upload performance** — pandas `DataFrame.to_sql` with chunked multi-row INSERTs
+- 💾 **Workflow persistence** — variable definitions survive save/reload without clicking Send first
+
+## Widgets
+
+| Widget | Description |
+|---|---|
+| **Time Features Constructor** | Defines new variables from existing ones using Python-style expressions and time-window functions. Supports chained descriptors with automatic topological sorting. |
+| **Variable Dependency Graph** | Builds a directed, weighted dependency graph from the variable definitions. Edge weights summarise how far back or forward in time each variable looks. |
+| **Save to DB** | Persists the resulting dataset to a SQL database (PostgreSQL or MySQL), with full SQL-injection defences, three write modes (create / overwrite / append) and an optional completion email. |
+| **Load from DB** | Lists datasets previously stored by Save to DB and pulls the chosen one back into Orange, optionally marking the class column directly so no Select Columns widget is needed. |
+
+## Installation
 
 ### Orange add-on installer
 
@@ -64,21 +86,10 @@ To install the add-on with pip use
 
     pip install TimeFeatures
 
-To install the add-on from source, run
-
-    python setup.py install
-
-To register this add-on with Orange, but keep the code in the development directory (do not copy it to 
-Python's site-packages directory), run
-
-    python setup.py develop
-
-You can also run
+To install the add-on from source in editable mode, run
 
     pip install -e .
 
-which is sometimes preferable as you can *pip uninstall* packages later.
-
 ### Anaconda
 
 If using Anaconda Python distribution, simply run
@@ -86,16 +97,18 @@ If using Anaconda Python distribution, simply run
     pip install TimeFeatures
 
 **Required Dependencies**:
+
 * numpy>=1.22.4
 * AnyQt>=0.2.0
-* Orange3>=3.34.0
 * PyQt5>=5.15.6
 * PyQtWebEngine>=5.15.6
 * scipy>=1.7.3
+* SQLAlchemy>=1.4.0
+* psycopg2-binary>=2.9.9
+* PyMySQL>=1.0.0
 * Orange3-Network>=1.8.0
 
-Usage
------
+## Usage
 
 After the installation, the widgets from this add-on are registered with Orange. To run Orange from the terminal,
 use
@@ -108,21 +121,25 @@ or
 
 New widgets are in the toolbox bar under Time-Features section.
 
-Documentation
--------------
+## Documentation
 
 The add-on includes Sphinx documentation for each widget. Orange resolves the
 local HTML pages through its internal Help panel, not through an internet URL.
 To rebuild the documentation locally, run
 
     pip install -e ".[docs]"
+    python -m sphinx -b html docs docs/build/html
+
+The bundled in-app help is pre-built under `timefeatures/help_html/`. To
+regenerate it (e.g. after editing the `.rst` files), run
+
     python -m sphinx -b html docs timefeatures/help_html
 
 Use the widget help action in Orange to open the corresponding page inside the
 Orange Help window.
 
-Workflow Example
------
+## Workflow Example
+
 This is an example of how you can use this add-on.
 
 ![Workflow](https://github.com/alervgr/Orange-TimeFeatures/blob/main/imgs/workflow.png?raw=true)

{timefeatures-2.0.0 → timefeatures-2.1.1}/TimeFeatures.egg-info/SOURCES.txt

@@ -21,9 +21,15 @@ docs/widgets/time-feature-constructor.rst
 docs/widgets/variable-dependency-graph.rst
 imgs/installation.png
 imgs/workflow.png
+imgs/widgets/owloadfromdb.png
+imgs/widgets/owsavetodb.png
+imgs/widgets/owtimefeaturesconstructor.png
+imgs/widgets/owvariabledependencygraph.png
 timefeatures/__init__.py
+timefeatures/__version__.py
 timefeatures/help.py
 timefeatures/help_html/.buildinfo
+timefeatures/help_html/.buildinfo.bak
 timefeatures/help_html/changes.html
 timefeatures/help_html/genindex.html
 timefeatures/help_html/index.html
@@ -31,6 +37,10 @@ timefeatures/help_html/installation.html
 timefeatures/help_html/objects.inv
 timefeatures/help_html/search.html
 timefeatures/help_html/searchindex.js
+timefeatures/help_html/_images/owloadfromdb.png
+timefeatures/help_html/_images/owsavetodb.png
+timefeatures/help_html/_images/owtimefeaturesconstructor.png
+timefeatures/help_html/_images/owvariabledependencygraph.png
 timefeatures/help_html/_sources/changes.rst.txt
 timefeatures/help_html/_sources/index.rst.txt
 timefeatures/help_html/_sources/installation.rst.txt

{timefeatures-2.0.0 → timefeatures-2.1.1}/docs/changes.rst

@@ -1,8 +1,8 @@
 Changelog
 =========
 
-Unreleased
-----------
+2.1.1 — 2026-06-09
+-------------------
 
 **Load from DB (new widget)**
 
@@ -22,6 +22,22 @@ Unreleased
 - Workflow-persisted settings: ``selected_dataset`` and
   ``selected_class`` are ``Setting(..., schema_only=True)``, restored
   as soon as the connection comes back up on reload.
+- The Dataset combo is a ``ComboBoxSearch`` — type to filter when the
+  registry gets large.
+- ``↻`` button next to the Dataset combo re-runs the listing without
+  dropping the connection (handy when something else just published a
+  new dataset). Auto-load is suppressed on Refresh so the user never
+  gets a Load they didn't ask for.
+- ``Delete`` button drops the selected dataset's table and removes
+  its row in ``datasets``. Runs through a ``_DeleteDatasetWorker`` on
+  a background thread, guarded by a confirmation dialog. Idempotent:
+  re-deleting a missing table is a no-op thanks to
+  ``DROP TABLE IF EXISTS``.
+- **Auto-load** on workflow reopen: if the persisted
+  ``selected_dataset`` is still on the server when the connection
+  succeeds and the listing returns, Load fires automatically — the
+  data flows out without a single click. The flag is cleared on
+  Refresh and on Delete to avoid surprises.
 
 **Variable Dependency Graph**
 
@@ -31,6 +47,17 @@ Unreleased
   reference the dependency. Plain (non-temporal) references default to
   weight ``1``. The weights live in ``network.edges[0].edges.data``
   and are consumable by any downstream Network widget.
+- *New:* the graph is now **directed** (``DirectedEdges``). Previously
+  the sparse matrix was passed straight to ``Network`` which auto-wrapped
+  it as ``UndirectedEdges`` — a latent bug since A→B is not the same as
+  B→A in a dependency graph.
+- *New:* nodes carry an extra ``expression`` meta (literal expression
+  text, empty for original variables) so the Network Explorer can show
+  the formula as the node label.
+- *New:* ``Warning.no_derived`` fires when every input row is an
+  original variable — usually a sign the user wired the data output
+  of Time Features Constructor instead of the variable-definitions
+  one.
 - Refactor: flattened the ``from_row_col`` / ``grafo`` decorator pattern
   into a single, documented ``build_dependency_network`` function.
 - Performance: O(n³) → O(n²) by precomputing a ``name → index`` map and
@@ -42,6 +69,16 @@ Unreleased
 
 **Time Features Constructor**
 
+- *New:* **chained descriptors**. A descriptor can now reference
+  another derived descriptor in its expression (e.g. ``X2 :=
+  shift(X1, -1)`` with ``X1`` itself defined a few rows above). The
+  widget topologically sorts the descriptors and cascades the
+  transforms — each step runs against the table state produced by
+  the previous one, so ``X2`` sees ``X1`` as a regular column.
+  Cycles (e.g. ``X1 := X2 + 1`` together with ``X2 := X1 + 1``) raise
+  a *Circular dependency between descriptors: X1, X2* error. Errors
+  during evaluation are reported per-descriptor so the failing row is
+  obvious.
 - *Fixed (critical):* time-window functions used to lose context every
   5 000 rows because Orange chunks tables during ``transform``. The
   widget now caches the full source per ``FeatureFunc`` and returns the
@@ -68,6 +105,15 @@ Unreleased
 
 **Save to DB**
 
+- *New:* **write mode** selector with three options — *Create new*
+  (default, fail if the target exists), *Overwrite* (drop and
+  recreate the table and its ``datasets`` row), *Append* (keep
+  existing rows and add the new ones). Re-running a workflow no
+  longer breaks. The persisted ``write_mode`` Setting defaults to
+  ``"create"`` so old workflows keep their previous behaviour. After
+  the upload, the widget runs ``SELECT COUNT(*)`` and rewrites the
+  ``datasets`` row with the actual total, so the registry stays
+  accurate across appends.
 - *New:* **MySQL support**. The connection panel now exposes a
   database-type selector (PostgreSQL / MySQL). Per-dialect column
   types and identifier quoting (``"name"`` vs ``\`name\```) live in

{timefeatures-2.0.0 → timefeatures-2.1.1}/docs/conf.py

@@ -10,7 +10,11 @@ sys.path.insert(0, str(ROOT))
 project = "TimeFeatures"
 author = "Alejandro Rivas Garcia"
 copyright = "2026, Alejandro Rivas Garcia"
-release = "1.0.18"
+
+# Read version from the single source of truth.
+_version_globals = {}
+exec((ROOT / "timefeatures" / "__version__.py").read_text(encoding="utf-8"), _version_globals)
+release = _version_globals["__version__"]
 version = ".".join(release.split(".")[:2])
 
 # -- General configuration ------------------------------------------------
@@ -47,7 +51,7 @@ html_theme_options = {
     "description": (
         "Time-series feature engineering for Orange3: build derived "
         "variables, visualise their dependencies, and persist data to "
-        "PostgreSQL."
+        "PostgreSQL or MySQL."
     ),
     "github_user": "alervgr",
     "github_repo": "Orange-TimeFeatures",

{timefeatures-2.0.0 → timefeatures-2.1.1}/docs/index.rst

@@ -81,11 +81,20 @@ Project
 Building this documentation
 ---------------------------
 
+**Development build** (for previewing locally):
+
 .. code-block:: bash
 
    pip install -e ".[docs]"
    python -m sphinx -b html docs docs/build/html
 
+**In-app help** (bundled with the wheel so Orange's Help panel works
+offline):
+
+.. code-block:: bash
+
+   python -m sphinx -b html docs timefeatures/help_html
+
 The HTML build is also bundled with the wheel so Orange's in-app help
 panel can resolve every widget's *Help* action without internet
 access.

{timefeatures-2.0.0 → timefeatures-2.1.1}/docs/widgets/load-from-db.rst

@@ -7,6 +7,11 @@ connects to a SQL database, lists the datasets previously persisted by
 ``Table`` — optionally marking the class column on the fly so no
 **Select Columns** widget is needed downstream.
 
+.. figure:: ../../imgs/widgets/owloadfromdb.png
+   :alt: Load from DB widget interface.
+
+   The Load from DB widget.
+
 Inputs
 ------
 
@@ -48,9 +53,21 @@ Controls
        host/db (N datasets)", "Loaded <name> (N rows)"), error
        ("Connection failed: …", "Load failed: …").
    * - Dataset
-     - Combo populated from ``SELECT * FROM datasets ORDER BY
-       datetime DESC``. The most recent upload comes first; the last
-       choice is restored when reopening a workflow.
+     - Searchable combo populated from ``SELECT * FROM datasets ORDER
+       BY datetime DESC``. The most recent upload comes first; the
+       last choice is restored when reopening a workflow. Type to
+       filter the visible items — handy when the registry grows large.
+   * - ↻ (Refresh)
+     - Small button to the right of the Dataset combo. Re-runs the
+       list query without dropping the connection. Useful if another
+       Orange canvas (or a parallel tool) just published a new
+       dataset while this widget was open.
+   * - Delete
+     - Drops the currently selected dataset's table from the database
+       and removes its row in ``datasets``. Gated by a confirmation
+       dialog — there is no Orange-side undo. The operation runs on a
+       background thread, so the canvas stays responsive even if the
+       table is large.
    * - Dataset info
      - Read-only block under the combo: save timestamp, row/column
        counts and the original class column recorded by **Save to DB**.
@@ -60,7 +77,9 @@ Controls
        choice, (2) the ``class_name`` stored in the ``datasets``
        metadata, (3) ``(no class)`` if none of the above apply.
    * - Load
-     - Triggers the actual download.
+     - Triggers the actual download. Skipped automatically on the
+       first connection after a workflow reopen if the persisted
+       dataset name is still available (see *Auto-load* below).
 
 How it Works
 ------------
@@ -88,6 +107,28 @@ While any worker runs, the form controls (database type, connection
 fields, **Connect**, **Load**, dataset and class combos) are
 temporarily disabled and the status label keeps the user informed.
 
+Auto-load
+---------
+
+When you reopen a workflow that already had a Load from DB widget with
+a saved ``selected_dataset``, the widget fires Load automatically the
+first time the dataset listing comes back successfully. The data flows
+out of the **Data** output without a single click, mirroring how Orange
+treats sources like **File** and **Datasets**.
+
+Subtleties:
+
+- Auto-load is a *one-shot* per widget lifetime. Manually clicking
+  **Refresh** clears the pending flag, so a Refresh never surprises
+  the user by loading something behind their back.
+- If the persisted dataset no longer exists on the server (deleted
+  from outside, or the registry was wiped), the flag is cleared and
+  the widget just shows the available list — no error.
+- If a different backend or set of credentials is restored, the user
+  still has to click **Connect** explicitly, just like in earlier
+  versions; auto-load happens *after* the first successful connection
+  + listing.
+
 Workflow Persistence
 --------------------
 

{timefeatures-2.0.0 → timefeatures-2.1.1}/docs/widgets/save-to-db.rst

@@ -7,6 +7,11 @@ database. Two dialects are supported out of the box:
 - **PostgreSQL** — through ``psycopg2``.
 - **MySQL** — through ``pymysql``.
 
+.. figure:: ../../imgs/widgets/owsavetodb.png
+   :alt: Save to DB widget interface.
+
+   The Save to DB widget.
+
 Both drivers are reached via **SQLAlchemy**, which keeps the SQL
 generation, identifier quoting and type rendering dialect-agnostic. The
 actual upload uses a `pandas <https://pandas.pydata.org/>`_ DataFrame
@@ -59,6 +64,21 @@ TimeFeatures-specific controls:
      - Destination table name. Validated against PostgreSQL identifier
        rules (see *Validation* below); MySQL accepts a superset, so
        the same rule is safe on both.
+   * - Mode
+     - Combo between the Table name and the Email fields:
+
+       - **Create new (fail if table exists)** — default, refuses to
+         touch an existing table or metadata row. Use this for first
+         uploads or when you want a clear error on accidental name
+         collisions.
+       - **Overwrite (drop and recreate)** — drops the existing data
+         table and the matching ``datasets`` row before uploading,
+         then recreates them. Re-running the workflow stops breaking.
+       - **Append (keep existing rows)** — adds rows to the existing
+         table (creating it if it doesn't exist). After the upload,
+         the widget runs ``SELECT COUNT(*)`` and rewrites the
+         ``datasets`` row with the *actual* total row count, so the
+         registry stays accurate across repeated appends.
    * - Email
      - Optional notification address. A summary email is sent once the
        upload finishes, including the table name, row / column counts,
@@ -79,12 +99,32 @@ When **Save** is clicked, the widget:
 
    - converts the dataset to a pandas DataFrame with
      ``Orange.data.pandas_compat.table_to_frame(include_metas=True)``
-     and reorders the columns (class first, then metas in domain order,
-     then attributes) to match the existing schema convention;
-   - creates the ``datasets`` metadata table if it doesn't exist;
-   - inserts one row into ``datasets`` describing this upload;
-   - writes the dataset itself in ``PANDAS_SQL_CHUNKSIZE`` chunks
-     (default ``1 000``) via ``df.to_sql(..., method='multi')``.
+     and reorders the columns (class first, then metas in domain
+     order, then attributes) to match the existing schema convention;
+   - ensures the ``datasets`` metadata table exists;
+   - applies the mode-specific preparation:
+
+     - **create** — fail fast if a ``datasets`` row with this name
+       already exists.
+     - **overwrite** — ``DROP TABLE IF EXISTS`` on the target plus
+       ``DELETE`` of the matching ``datasets`` row.
+     - **append** — leave everything in place; the upload itself will
+       create the table on the first chunk if it doesn't exist.
+
+   - writes the dataset in ``PANDAS_SQL_CHUNKSIZE`` chunks (default
+     ``1 000``) via ``df.to_sql(..., method='multi')`` with the
+     ``if_exists`` value tailored to the mode (see
+     ``_pandas_if_exists`` for the exact table);
+   - runs ``SELECT COUNT(*)`` on the target table and re-inserts the
+     ``datasets`` row with that real row count, so the registry stays
+     consistent even after multiple appends.
+
+Everything happens inside a single SQLAlchemy transaction
+(``engine.begin()``), so a mid-upload error rolls every step back on
+PostgreSQL. MySQL auto-commits DDL (``DROP TABLE``, ``CREATE TABLE``),
+so an Overwrite that crashes during the upload may leave you without
+the original table — there's no way around that without engine-level
+support.
 
 While the worker runs, the widget's progress bar and status label are
 updated through Qt signals; the **Save**, **Connect** and form controls