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| needs Python 3.10 or newer and declares the following runtime
dependencies (see ``setup.py``):

.. list-table::
   :header-rows: 1

   * - Package
     - Minimum version
     - Used by
   * - ``Orange3``
     - 3.36.2
     - Host application and data model. Older releases do not work with
       NumPy 2.
   * - ``numpy``
     - 1.22.4
     - All widgets.
   * - ``scipy``
     - 1.7.3
     - Sparse adjacency matrices in the dependency graph.
   * - ``PyQt5``
     - 5.15.6
     - Widget UI.
   * - ``PyQtWebEngine``
     - 5.15.6
     - Orange's in-app help window.
   * - ``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 is listed explicitly so a clean ``pip install`` gets a version
the add-on is tested with. Inside an existing Orange installation that
already meets the minimum, pip leaves it untouched.

The CI workflow (``.github/workflows/ci.yml``) runs the test suite on
Python 3.10 with Orange3 3.36.2 and on Python 3.11 and 3.12 with the
latest releases, builds the package and installs the wheel into an
empty environment, and builds this documentation with warnings as
errors.

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.

The Save to DB upload tests always run on SQLite. To also run them
against real servers, point these variables to **disposable** databases
(the tests create and drop tables there):

.. code-block:: bash

   export TIMEFEATURES_TEST_POSTGRES_URL=postgresql://user:pass@localhost:5432/timefeatures_test
   export TIMEFEATURES_TEST_MYSQL_URL=mysql://user:pass@127.0.0.1:3306/timefeatures_test
