TimeFeatures 1.0.18__tar.gz → 2.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TimeFeatures
-Version: 1.0.18
+Version: 2.0.0
 Summary: Timefeatures add-on for Orange 3 data mining software.
 Home-page: https://github.com/alervgr/Orange-TimeFeatures
 Author: Alejandro Rivas García
@@ -23,7 +23,9 @@ Requires-Dist: AnyQt>=0.2.0
 Requires-Dist: PyQt5>=5.15.6
 Requires-Dist: PyQtWebEngine>=5.15.6
 Requires-Dist: scipy>=1.7.3
+Requires-Dist: SQLAlchemy>=1.4.0
 Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: PyMySQL>=1.0.0
 Requires-Dist: Orange3-Network>=1.8.0
 Provides-Extra: docs
 Requires-Dist: Sphinx>=7.0; extra == "docs"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TimeFeatures
-Version: 1.0.18
+Version: 2.0.0
 Summary: Timefeatures add-on for Orange 3 data mining software.
 Home-page: https://github.com/alervgr/Orange-TimeFeatures
 Author: Alejandro Rivas García
@@ -23,7 +23,9 @@ Requires-Dist: AnyQt>=0.2.0
 Requires-Dist: PyQt5>=5.15.6
 Requires-Dist: PyQtWebEngine>=5.15.6
 Requires-Dist: scipy>=1.7.3
+Requires-Dist: SQLAlchemy>=1.4.0
 Requires-Dist: psycopg2-binary>=2.9.9
+Requires-Dist: PyMySQL>=1.0.0
 Requires-Dist: Orange3-Network>=1.8.0
 Provides-Extra: docs
 Requires-Dist: Sphinx>=7.0; extra == "docs"

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

@@ -10,9 +10,12 @@ TimeFeatures.egg-info/entry_points.txt
 TimeFeatures.egg-info/requires.txt
 TimeFeatures.egg-info/top_level.txt
 docs/Makefile
+docs/changes.rst
 docs/conf.py
 docs/index.rst
+docs/installation.rst
 docs/requirements.txt
+docs/widgets/load-from-db.rst
 docs/widgets/save-to-db.rst
 docs/widgets/time-feature-constructor.rst
 docs/widgets/variable-dependency-graph.rst
@@ -21,12 +24,17 @@ imgs/workflow.png
 timefeatures/__init__.py
 timefeatures/help.py
 timefeatures/help_html/.buildinfo
+timefeatures/help_html/changes.html
 timefeatures/help_html/genindex.html
 timefeatures/help_html/index.html
+timefeatures/help_html/installation.html
 timefeatures/help_html/objects.inv
 timefeatures/help_html/search.html
 timefeatures/help_html/searchindex.js
+timefeatures/help_html/_sources/changes.rst.txt
 timefeatures/help_html/_sources/index.rst.txt
+timefeatures/help_html/_sources/installation.rst.txt
+timefeatures/help_html/_sources/widgets/load-from-db.rst.txt
 timefeatures/help_html/_sources/widgets/save-to-db.rst.txt
 timefeatures/help_html/_sources/widgets/time-feature-constructor.rst.txt
 timefeatures/help_html/_sources/widgets/variable-dependency-graph.rst.txt
@@ -43,14 +51,17 @@ timefeatures/help_html/_static/plus.png
 timefeatures/help_html/_static/pygments.css
 timefeatures/help_html/_static/searchtools.js
 timefeatures/help_html/_static/sphinx_highlight.js
+timefeatures/help_html/widgets/load-from-db.html
 timefeatures/help_html/widgets/save-to-db.html
 timefeatures/help_html/widgets/time-feature-constructor.html
 timefeatures/help_html/widgets/variable-dependency-graph.html
 timefeatures/widgets/__init__.py
+timefeatures/widgets/owloadfromdb.py
 timefeatures/widgets/owsavetodb.py
 timefeatures/widgets/owtimefeaturesconstructor.py
 timefeatures/widgets/owvardependencygraph.py
 timefeatures/widgets/icons/graphgenerator.svg
+timefeatures/widgets/icons/loaddatadb.svg
 timefeatures/widgets/icons/savedatadb.svg
 timefeatures/widgets/icons/timefeature-xs.svg
 timefeatures/widgets/icons/timefeature.svg

{timefeatures-1.0.18 → timefeatures-2.0.0}/TimeFeatures.egg-info/requires.txt

@@ -3,7 +3,9 @@ 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
 
 [docs]

timefeatures-2.0.0/docs/changes.rst

@@ -0,0 +1,121 @@
+Changelog
+=========
+
+Unreleased
+----------
+
+**Load from DB (new widget)**
+
+- Lists every dataset registered in the ``datasets`` metadata table
+  via SQLAlchemy and pulls the selected one back into Orange as an
+  ``Orange.data.Table`` using ``pandas.read_sql`` +
+  ``Orange.data.pandas_compat.table_from_frame``.
+- Offers a Class column combo populated from the dataset's columns,
+  pre-selected with the user's persisted choice or the ``class_name``
+  recorded by Save to DB. The output ``Table`` already exposes the
+  chosen column as ``domain.class_var``, so no Select Columns widget
+  is needed downstream.
+- Same dialect selector (PostgreSQL / MySQL), connection-status
+  label and ``QThread`` worker pattern as Save to DB. Both the
+  metadata listing and the actual table read happen off the GUI
+  thread.
+- Workflow-persisted settings: ``selected_dataset`` and
+  ``selected_class`` are ``Setting(..., schema_only=True)``, restored
+  as soon as the connection comes back up on reload.
+
+**Variable Dependency Graph**
+
+- *New:* edges now carry **numeric weights** equal to the largest
+  ``|argument|`` among the temporal calls (``shift``, ``sum``, ``mean``,
+  ``count``, ``min``, ``max``, ``sd``) in the source expression that
+  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.
+- 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
+  using a ``set`` to dedupe dependencies.
+- Bugfix: an ``IndexError`` was raised when the input domain had a
+  single column. The widget now checks ``len(domain) >= 2`` before
+  reading the second column.
+- Removed 65 lines of dead commented-out code.
+
+**Time Features Constructor**
+
+- *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
+  right slice for each chunk, so ``shift(x, -20)`` is correct across
+  chunk boundaries on datasets of any size.
+- *Fixed:* "Variables to generate" was being cleared after every Send
+  and on every input change, so workflow save / reload lost the
+  definitions. Storage moved from ``ContextSetting`` to
+  ``Setting(..., schema_only=True)`` (matching upstream Orange v4) and
+  the editor is now restored from the persisted descriptors on every
+  input. The legacy context handler stays around to migrate old
+  workflows.
+- Each **Send** re-transforms the *original* input table instead of the
+  cumulative output, removing the implicit "consume on Send" semantics
+  and the duplicate-name errors that came with it.
+- ``eval`` hardened: ``__builtins__`` replaced with an empty dict in
+  the expression evaluator. Only the curated whitelist
+  (safe builtins + ``math`` + selected ``random`` / ``numpy``
+  helpers) is exposed.
+- Refactor: ``modificar_expression`` collapsed from 7 near-identical
+  loops to a single regex-driven pass.
+- Bugfix: ``FeatureEditor.editorData`` returned the variable name as
+  the expression.
+
+**Save to DB**
+
+- *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
+  a ``_Dialect`` abstraction.
+- *Performance:* uploads now go through
+  ``Orange.data.pandas_compat.table_to_frame`` +
+  ``DataFrame.to_sql(method='multi', chunksize=1000)`` over a
+  SQLAlchemy engine. The old row-per-INSERT loop is gone — typical
+  speedups are 50-100×, especially over the network. Identifier
+  quoting and per-column DDL types are emitted by the SQLAlchemy
+  dialect (``DOUBLE_PRECISION`` on PostgreSQL, ``DOUBLE`` on MySQL,
+  ``DATETIME`` instead of ``TIMESTAMP`` on MySQL to dodge the 2038
+  cap, ``VARCHAR(255)`` / ``TEXT`` everywhere else).
+- *UX:* the upload runs in a background ``QThread`` (``_UploadWorker``),
+  so the canvas stays interactive on long writes. A status label under
+  the connection box reports *Not connected* / *Connected to … : …* /
+  *Uploading rows N/M…* / *Upload completed in Xs* / *Upload failed:
+  …* with colour cues. **Save**, **Connect** and the form fields are
+  disabled while the worker runs and re-enabled on success or
+  failure; the widget aborts the thread cleanly on close.
+- *Fixed (critical):* SQL injection in the metadata ``INSERT``. The
+  query is now fully parametrised.
+- Added an identifier whitelist
+  (``^[A-Za-z_][A-Za-z0-9_]{0,62}$``) and a ``quote_ident`` helper that
+  wraps identifiers with PostgreSQL-standard double quotes (with any
+  internal ``"`` doubled). Used in every ``CREATE TABLE`` / ``INSERT
+  INTO`` that touches user-supplied names.
+- Replaced ``psycopg2`` with ``psycopg2-binary`` in the install
+  requirements so installation works on macOS, Linux and Windows
+  without a C compiler.
+- ``setup.py`` now declares ``install_requires``; ``pip install`` was
+  previously not pulling in any runtime dependency.
+
+Testing
+-------
+
+The widget suite grew to **92 tests**, covering:
+
+- Unit tests for ``modificar_expression``, the time-window helpers,
+  ``_sanitize_name`` / ``_expression_or_none`` and ``_temporal_weights``.
+- A regression test for the 5 000-row chunk bug
+  (``shift(x, -20)`` over a 12 000-row table).
+- ``eval``-safety tests asserting that ``__import__`` / ``open`` raise
+  ``NameError`` while ``sqrt`` / ``abs`` still resolve.
+- Widget-level tests (via ``Orange.widgets.tests.base.WidgetTest``) for
+  descriptor persistence, including an end-to-end
+  ``settingsHandler.pack_data`` / ``stored_settings=`` round-trip that
+  mirrors what Orange does when saving and reopening a ``.ows`` file.
+- Edge-weight tests covering single calls, three-argument families,
+  mixed temporal / non-temporal references, max across multiple calls,
+  and per-dependency independence.

timefeatures-2.0.0/docs/conf.py

@@ -0,0 +1,62 @@
+"""Sphinx configuration for TimeFeatures."""
+
+from pathlib import Path
+import sys
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+# -- Project information --------------------------------------------------
+project = "TimeFeatures"
+author = "Alejandro Rivas Garcia"
+copyright = "2026, Alejandro Rivas Garcia"
+release = "1.0.18"
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ------------------------------------------------
+extensions = [
+    # Auto-generate :ref: labels from section titles so we can write
+    # `:ref:`Edge Weights`` instead of declaring labels by hand.
+    "sphinx.ext.autosectionlabel",
+    # Link to Orange / NumPy / SciPy reference docs.
+    "sphinx.ext.intersphinx",
+]
+
+# Prefix labels with the document name so two pages can share the same
+# section title (e.g. "Usage Example") without clashing.
+autosectionlabel_prefix_document = True
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+    "orange": ("https://orange3.readthedocs.io/projects/orange-data-mining-library/en/latest/", None),
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
+
+language = "en"
+
+# -- HTML output ----------------------------------------------------------
+html_theme = "alabaster"
+html_static_path = []
+html_title = "TimeFeatures documentation"
+html_short_title = "TimeFeatures"
+html_theme_options = {
+    "description": (
+        "Time-series feature engineering for Orange3: build derived "
+        "variables, visualise their dependencies, and persist data to "
+        "PostgreSQL."
+    ),
+    "github_user": "alervgr",
+    "github_repo": "Orange-TimeFeatures",
+    "github_banner": True,
+    "show_powered_by": False,
+    "fixed_sidebar": True,
+}
+
+# Default replacements for any RST file (no need to redeclare per page).
+rst_prolog = """
+.. |addon| replace:: TimeFeatures
+"""

timefeatures-2.0.0/docs/index.rst

@@ -0,0 +1,97 @@
+TimeFeatures
+============
+
+|addon| is an `Orange3 <https://orangedatamining.com/>`_ add-on for
+time-series feature engineering. It ships four widgets that work
+together to define, visualise, persist and re-load derived variables
+built on top of an existing dataset.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Widget
+     - What it does
+   * - :doc:`widgets/time-feature-constructor`
+     - Defines new variables from existing ones using Python-style
+       expressions and time-window functions (``shift``, ``sum``,
+       ``mean``, ``min``, ``max``, ``sd``, ``count``).
+   * - :doc:`widgets/variable-dependency-graph`
+     - Builds a directed, **weighted** dependency graph from the
+       resulting variable / expression table. Edge weights summarise
+       how far back or forward in time each variable looks.
+   * - :doc:`widgets/save-to-db`
+     - Persists the resulting dataset to a SQL database (PostgreSQL
+       or MySQL), with full SQL-injection defences and an optional
+       completion email.
+   * - :doc:`widgets/load-from-db`
+     - Lists the 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.
+
+.. _workflow:
+
+Workflow
+--------
+
+A typical pipeline:
+
+.. code-block:: text
+
+   File → Time Features Constructor → ┬→ <downstream models>
+                                      └→ Variable Dependency Graph
+                                              ↓
+                                      Network Explorer
+
+The **Time Features Constructor** outputs both the transformed data
+(top arrow) and the variable / expression definition table (bottom
+arrow). Feed the latter into the **Variable Dependency Graph** to
+visualise the dependencies, and send the data into **Save to DB** if
+you want to keep it in a database.
+
+Getting started
+---------------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+
+.. _widgets:
+
+Widgets
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   widgets/time-feature-constructor
+   widgets/variable-dependency-graph
+   widgets/save-to-db
+   widgets/load-from-db
+
+Project
+-------
+
+.. toctree::
+   :maxdepth: 1
+
+   changes
+
+Building this documentation
+---------------------------
+
+.. code-block:: bash
+
+   pip install -e ".[docs]"
+   python -m sphinx -b html docs docs/build/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.
+
+Indices
+-------
+
+* :ref:`genindex`
+* :ref:`search`

timefeatures-2.0.0/docs/installation.rst

@@ -0,0 +1,103 @@
+Installation
+============
+
+|addon| is an Orange3 add-on, so it requires a working Orange3
+installation in the same Python environment.
+
+From PyPI
+---------
+
+.. code-block:: bash
+
+   pip install TimeFeatures
+
+This pulls in every runtime dependency, including the precompiled
+``psycopg2-binary`` wheel so the **Save to DB** widget works on macOS,
+Linux and Windows without a C toolchain.
+
+From source
+-----------
+
+.. code-block:: bash
+
+   git clone https://github.com/alervgr/Orange-TimeFeatures.git
+   cd Orange-TimeFeatures
+   pip install -e .
+
+The ``-e`` flag installs in *editable* mode so changes to the source
+tree are picked up on the next Orange restart without reinstalling.
+
+Inside Orange
+-------------
+
+|addon| also installs through Orange's GUI:
+
+1. Open Orange.
+2. Go to **Options → Add-ons…**.
+3. Tick **TimeFeatures** in the list and confirm.
+4. Restart Orange. The new widgets appear under the **Time-Features**
+   toolbox section.
+
+.. image:: https://github.com/alervgr/Orange-TimeFeatures/blob/main/imgs/installation.png?raw=true
+   :alt: TimeFeatures in Orange's Add-on installer.
+
+Anaconda
+--------
+
+The same ``pip install TimeFeatures`` command works inside a Conda
+environment as long as Orange3 is installed there.
+
+Dependencies
+------------
+
+|addon| declares the following runtime dependencies (see
+``setup.py``):
+
+.. list-table::
+   :header-rows: 1
+
+   * - Package
+     - Minimum version
+     - Used by
+   * - ``numpy``
+     - 1.22.4
+     - All widgets.
+   * - ``scipy``
+     - 1.7.3
+     - Sparse adjacency matrices in the dependency graph.
+   * - ``PyQt5``
+     - 5.15.6
+     - Widget UI.
+   * - ``AnyQt``
+     - 0.2.0
+     - Qt abstraction used by Orange.
+   * - ``SQLAlchemy``
+     - 1.4.0
+     - Dialect-agnostic SQL toolkit used by **Save to DB**.
+   * - ``psycopg2-binary``
+     - 2.9.9
+     - PostgreSQL driver for **Save to DB**.
+   * - ``PyMySQL``
+     - 1.0.0
+     - MySQL driver for **Save to DB**.
+   * - ``Orange3-Network``
+     - 1.8.0
+     - ``Network`` type produced by **Variable Dependency Graph**.
+
+Orange3 itself is intentionally left out of the requirements list — the
+host application provides it.
+
+Running tests
+-------------
+
+The test suite uses ``unittest`` and lives under
+``timefeatures/widgets/tests/``. From a checkout:
+
+.. code-block:: bash
+
+   pip install -e .
+   python -m unittest discover -v timefeatures/widgets/tests
+
+The widget-level tests inherit from ``Orange.widgets.tests.base.WidgetTest``
+and therefore require Qt; a virtual display (``Xvfb``) is enough on a
+headless CI worker.

timefeatures-2.0.0/docs/widgets/load-from-db.rst

@@ -0,0 +1,136 @@
+Load from DB
+============
+
+The **Load from DB** widget is the inverse of :doc:`save-to-db`. It
+connects to a SQL database, lists the datasets previously persisted by
+**Save to DB**, and pulls the selected one back into Orange as a
+``Table`` — optionally marking the class column on the fly so no
+**Select Columns** widget is needed downstream.
+
+Inputs
+------
+
+This widget has no input signals.
+
+Outputs
+-------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Signal
+     - Type
+     - Description
+   * - Data
+     - ``Orange.data.Table``
+     - The loaded dataset. If the user picks a class column, the
+       resulting domain already exposes it as the class variable; all
+       other columns stay in ``domain.attributes`` and the metas
+       declared in the SQL schema (if any) remain as ``domain.metas``.
+
+Controls
+--------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Field
+     - Description
+   * - Database type
+     - Combo box at the top of the connection box. Pick **PostgreSQL**
+       or **MySQL**. The driver and quoting rules adapt automatically
+       through the same :class:`_Dialect` abstraction the **Save to
+       DB** widget uses.
+   * - Connection status
+     - Small label under the connection box. Shows three states:
+       neutral ("Not connected", "Connecting…", "Listing datasets…",
+       "Loading <name>…"), success ("Connected to PostgreSQL:
+       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.
+   * - Dataset info
+     - Read-only block under the combo: save timestamp, row/column
+       counts and the original class column recorded by **Save to DB**.
+   * - Class column
+     - Combo with every column of the selected dataset plus a
+       ``(no class)`` sentinel. Defaults to (1) the user's persisted
+       choice, (2) the ``class_name`` stored in the ``datasets``
+       metadata, (3) ``(no class)`` if none of the above apply.
+   * - Load
+     - Triggers the actual download.
+
+How it Works
+------------
+
+When the **Connect** button is clicked, the widget validates the
+connection through ``OWBaseSql`` (the same path Save to DB uses) and
+then spawns a background ``QThread`` that runs a
+``_ListDatasetsWorker``. The worker queries the ``datasets`` metadata
+table via SQLAlchemy and emits the result back to the GUI thread.
+
+Selecting a dataset triggers a tiny ``SELECT * FROM <name> LIMIT 0``
+to fetch the column list — this is cheap enough to run synchronously
+because the server only returns the column header.
+
+When **Load** is clicked, a ``_LoadTableWorker`` runs
+``pandas.read_sql("SELECT * FROM <name>", engine)`` on a background
+thread, returning a DataFrame that the GUI thread converts into an
+``Orange.data.Table`` with
+``Orange.data.pandas_compat.table_from_frame``. If the user picked a
+class column, the helper ``_build_domain_with_class`` rebuilds the
+domain so that column becomes ``domain.class_var`` and the rest of the
+columns stay in ``domain.attributes``.
+
+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.
+
+Workflow Persistence
+--------------------
+
+Two ``Setting``\\s are persisted with the workflow:
+
+- ``selected_dataset`` — the name picked in the Dataset combo.
+- ``selected_class`` — the name picked in the Class combo
+  (``""`` means "no class").
+
+Both are declared as ``Setting(..., schema_only=True)``, mirroring the
+**Time Features Constructor** convention: the values live in the
+``.ows`` file but never become global defaults. On reopening a
+workflow, the widget restores the choices as soon as the connection
+succeeds and the dataset list arrives.
+
+Usage Example
+-------------
+
+Round-tripping a dataset through the database:
+
+1. In one Orange workflow, attach a **File** widget to **Save to DB**
+   and upload the data with a chosen table name.
+2. In another workflow (or the same one), drop a **Load from DB**
+   widget.
+3. Pick the database type, fill in the connection fields, and click
+   **Connect**.
+4. Pick the dataset in the Dataset combo. The info block shows the
+   timestamp and the original class.
+5. Override the Class column if you want a different target, or leave
+   the default to keep the original one.
+6. Click **Load**. The table flows out of the **Data** output ready
+   for any downstream Orange widget — no **Select Columns** in
+   between.
+
+Requirements
+------------
+
+|addon| brings every dependency the widget needs:
+
+.. code-block:: text
+
+   SQLAlchemy>=1.4.0       # dialect-agnostic SQL toolkit
+   psycopg2-binary>=2.9.9  # PostgreSQL driver
+   PyMySQL>=1.0.0          # MySQL driver
+
+``pandas`` itself is a transitive dependency of Orange3.