Create Login (#2)

* first cut

* Docs and docstrings

* add qtbot

* update fixtures

* fix  pytest

* Fix docs build

* updates and fixes

* cleanup and refactor

* update docs

* fix link

.gitignore

@@ -53,6 +53,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+tests/data/token.json
 
 # Translations
 *.mo

.readthedocs.yaml

@@ -12,7 +12,7 @@ python:
 
 sphinx:
   builder: html
-  configuration: docs/source/conf.py
+  configuration: docs/conf.py
   fail_on_warning: true
 
 conda:

conda.recipe/meta.yaml

@@ -35,6 +35,9 @@ requirements:
 
   run:
     - python
+    - pyoncat
+    - oauthlib
+    - mantidqt
 
 about:
   home: {{ url }}

docs/Makefile

@@ -0,0 +1,21 @@
+# Purpose: Convenience scripts to simplify some common Sphinx operations, such as rendering the content.
+
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -38,7 +38,16 @@
     "sphinx.ext.githubpages",
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
+    "sphinxcontrib.mermaid",
 ]
+
+autodoc_mock_imports = [
+    "qtpy",
+    "qtpy.uic",
+    "qtpy.QtWidgets",
+    "mantidqt",
+]
+
 templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
@@ -69,7 +78,9 @@
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 
-html_static_path = ["_static"]
+# html_static_path = ["source/_static"]
+
+html_theme_options = {"page_width": "75%"}
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True

docs/index.rst

@@ -0,0 +1,33 @@
+.. Purpose: The root document of the project, which serves as welcome page and contains the root
+.. of the "table of contents tree" (or toctree).
+
+PyONCatQt Documentation
+=======================
+
+PyONCatQt is a Python package designed to provide a Qt-based GUI for authentication
+and connection to the ONCat service, a data cataloging and management system developed
+by Oak Ridge National Laboratory. It serves as a plugin for other applications,
+offering a convenient PyQt-based GUI component,
+ONCatLoginDialog, for securely inputting login credentials. Upon successful authentication,
+the package establishes a connection to the ONCat service, granting access to various data
+management functionalities. PyONCatQt aims to streamline the login process and enhance user
+experience when interacting with ONCat within Python applications.
+
+Getting Started
+---------------
+To install PyONCatQt, run the following command:
+
+.. code-block:: bash
+
+   conda install -c neutrons pyoncatqt
+
+To use PyONCatQt please see the :ref:`sample` section for examples.
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   source/reference
+   source/sample

docs/make.bat

@@ -0,0 +1,37 @@
+REM Purpose: Convenience scripts to simplify some common Sphinx operations, such as rendering the content.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/reference.rst

@@ -0,0 +1,16 @@
+Reference
+=========
+
+ONCatLogin
+----------
+
+.. module:: ONCatLogin
+.. automodule:: pyoncatqt.login.ONCatLogin
+    :members:
+
+ONCatLoginDialog
+----------------
+
+.. module:: ONCatLoginDialog
+.. automodule:: pyoncatqt.login.ONCatLoginDialog
+    :members:

docs/source/sample.rst

@@ -0,0 +1,148 @@
+.. _sample:
+
+Sample Usage
+============
+
+ONCatLogin Widget
+-----------------
+The following is a simple example of how to use the ONCatLogin widget in a PyQt application.
+This example creates a main window with an ONCatLogin widget and two QListWidgets to display
+the instrument lists for the SNS and HFIR facilities. The instrument lists are updated when
+the connection status changes.
+The only required argument for the ``ONCatLogin`` widget is the client ID. The client ID is a unique identifier
+for the application that is used to authenticate with the ONCat server. The client ID is provided by the ONCat support team.
+and should exist in pyoncatqt configuration file.
+
+.. code:: python
+
+    from pyoncatqt.login import ONCatLogin
+    from qtpy.QtWidgets import QApplication, QLabel, QListWidget, QVBoxLayout, QWidget
+
+    class MainWindow(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.initUI()
+
+    def initUI(self):
+        layout = QVBoxLayout()
+
+        # Create and add the Oncat widget
+        self.oncat_widget = ONCatLogin(key="", parent=self)
+        self.oncat_widget.connection_updated.connect(self.update_instrument_lists)
+        layout.addWidget(self.oncat_widget)
+
+        # Add list widgets for the instrument lists
+        self.sns_list = QListWidget()
+        self.hfir_list = QListWidget()
+
+        layout.addWidget(QLabel("SNS Instruments:"))
+        layout.addWidget(self.sns_list)
+        layout.addWidget(QLabel("HFIR Instruments:"))
+        layout.addWidget(self.hfir_list)
+
+        self.setLayout(layout)
+        self.setWindowTitle("ONCat Application")
+        self.oncat_widget.update_connection_status()
+
+    def update_instrument_lists(self, is_connected):
+        """Update the contents of the instrument lists based on the connection status."""
+        self.sns_list.clear()
+        self.hfir_list.clear()
+
+        if is_connected:
+            sns_instruments = self.oncat_widget.agent.Instrument.list(facility="SNS")
+            hfir_instruments = self.oncat_widget.agent.Instrument.list(facility="HFIR")
+
+            for instrument in sns_instruments:
+                self.sns_list.addItem(instrument.get("name"))
+
+            for instrument in hfir_instruments:
+                self.hfir_list.addItem(instrument.get("name"))
+
+    if __name__ == "__main__":
+        app = QApplication(sys.argv)
+        window = MainWindow()
+        window.show()
+        sys.exit(app.exec_())
+
+
+ONCatLoginDialog
+----------------
+
+The `ONCatLoginDialog` can be imported and used separate from the `ONCatLogin` widget to give developers
+the ability to customize the login process. In order to use the `ONCatLoginDialog`, you must have an
+instance of the `pyoncat.ONCat` agent.
+If you chose to use the `ONCatLogin` widget instead, the agent is already created for you.
+The `ONCatLoginDialog` requires the agent to be passed in as an argument.
+The agent is used to authenticate the user and manage the connection to the ONCat server.
+At a minimum the agent must be initialized with the ONCat server URL, flow, and the client ID.
+Additional callbacks can be passed in to handle token storage and retrieval. These would be simple functions to read and write
+the token to a JSON file.
+
+.. code:: python
+
+    import pyoncat
+
+    # This is a temporary "client ID" intended for use in this tutorial **only**.
+    # For your own work, please contact ONCat Support to be issued your own credentials.
+    CLIENT_ID = "c0686270-e983-4c71-bd0e-bfa47243a47f"
+
+    # We will use the testing version of ONCat for this sample.
+    ONCAT_URL = "https://oncat-testing.ornl.gov"
+
+    oncat = pyoncat.ONCat(
+        ONCAT_URL,
+        client_id=CLIENT_ID,
+        flow=pyoncat.RESOURCE_OWNER_CREDENTIALS_FLOW,
+    )
+
+The following example demonstrates how to use the `ONCatLoginDialog` in a PyQt application.
+
+- The application consists of a single button labeled "Login to ONCat".
+- When the button is clicked, it triggers the opening of the `ONCatLoginDialog`,
+  allowing the user to input their ONCat login credentials securely.
+- Upon successful login, the dialog closes, and the application can proceed with its functionality,
+  utilizing the authenticated ONCat connection for data management tasks.
+
+.. code:: python
+
+    from pyoncatqt.login import ONCatLoginDialog
+    import pyoncat
+    from qtpy.QtWidgets import QApplication, QPushButton, QVBoxLayout, QWidget
+    import sys
+
+    class MainWindow(QWidget):
+        def __init__(self):
+            super().__init__()
+            self.initUI()
+
+        def initUI(self):
+            layout = QVBoxLayout()
+
+            # Create a button to open the ONCat login dialog
+            self.login_button = QPushButton("Login to ONCat")
+            self.login_button.clicked.connect(self.open_oncat_login_dialog)
+            layout.addWidget(self.login_button)
+            self.setLayout(layout)
+            self.setWindowTitle("ONCat Login Example")
+
+            # Create an instance of the pyoncat agent pyoncat.ONCat
+            CLIENT_ID = "c0686270-e983-4c71-bd0e-bfa47243a47f"
+
+            ONCAT_URL = "https://oncat-testing.ornl.gov"
+
+            self.agent = pyoncat.ONCat(
+                ONCAT_URL,
+                client_id=CLIENT_ID,
+                flow=pyoncat.RESOURCE_OWNER_CREDENTIALS_FLOW,
+            )
+
+        def open_oncat_login_dialog(self):
+            dialog = ONCatLoginDialog(agent=self.agent, parent=self)
+            dialog.exec_()
+
+    if __name__ == "__main__":
+        app = QApplication(sys.argv)
+        window = MainWindow()
+        window.show()
+        sys.exit(app.exec_())

environment.yml

@@ -15,5 +15,8 @@ dependencies:
   - python-build
   - pytest
   - pytest-cov
+  - pytest-qt
   - setuptools
+  - sphinx
+  - sphinxcontrib-mermaid
   - versioningit

pyproject.toml

@@ -30,29 +30,37 @@ file = "src/pyoncatqt/_version.py"
 
 [tool.setuptools.packages.find]
 where = ["src"]
-exclude = ["tests*", "docs*"]
+exclude = ["tests*", "docs*", "scripts*"]
+
+[project.gui-scripts]
+pyoncatqt = "pyoncatqt.version:get_version"
 
 [tool.setuptools.package-data]
 "*" = ["*.yml","*.yaml","*.ini"]
 
-# TODO: Define once the package is ready for distribution
-#[project.scripts]
-#packagename-cli = "packagenamepy.packagename:main"
-
-#[project.gui-scripts]
-#packagenamepy = "packagenamepy.packagename:gui"
-
 [tool.pytest.ini_options]
-pythonpath = [".", "src", "scripts"]
+pythonpath = [".", "src"]
 testpaths = ["tests"]
 python_files = ["test*.py"]
 norecursedirs = [".git", "tmp*", "_tmp*", "__pycache__", "*dataset*", "*data_set*"]
 
+[tool.coverage.report]
+exclude_lines = [
+    "except ImportError:",
+    "except ModuleNotFoundError:",
+    "except pyoncat.LoginRequiredError:",
+    "except pyoncat.InvalidRefreshTokenError:",
+    "except Exception:",
+    "except json.JSONDecodeError:",
+    "except KeyError:",
+]
+omit = ["src/pyoncatqt/_version.py"]
+
 [tool.ruff]
 line-length = 120
 
 [tool.ruff.lint]
 # https://beta.ruff.rs/docs/rules/
-select = ["A", "ARG", "BLE", "E", "F", "I", "PT"]
+select = ["A", "ARG", "BLE", "E", "F", "I", "PT", "ANN"]
 ignore = ["F403", "F405", "F401", # wild imports and  unknown names
 ]