Merge pull request #11 from aaronweeden/rename-package

Rename package to `xdmod-data` and prepare for v1.0.0 release.

Author: aaronweeden

LICENSE

@@ -0,0 +1,58 @@
+# xdmod-data
+As part of the [XDMoD](https://open.xdmod.org) Data Analytics Framework, this Python package provides API access to the data warehouse of an instance of XDMoD version ≥10.5.
+
+The package can be installed from PyPI via `pip install xdmod-data`.
+
+It has dependencies on [NumPy](https://pypi.org/project/numpy/), [Pandas](https://pypi.org/project/pandas/), [Plotly](https://pypi.org/project/plotly/), and [Requests](https://pypi.org/project/requests/).
+
+Example usage is documented through Jupyter notebooks in the [xdmod-notebooks](https://github.com/ubccr/xdmod-notebooks) repository.
+
+## API Token Access
+Use of the Data Analytics Framework requires an API token. To obtain an API token, follow the steps below to obtain an API token from the XDMoD portal.
+
+1. First, if you are not already signed in to the portal, sign in in the top-left corner:
+
+    ![Screenshot of "Sign In" button](https://raw.githubusercontent.com/ubccr/xdmod-data/main/docs/images/api-token/sign-in.jpg)
+
+1. Next, click the "My Profile" button in the top-right corner:
+
+    ![Screenshot of "My Profile" button](https://raw.githubusercontent.com/ubccr/xdmod-data/main/docs/images/api-token/my-profile.jpg)
+
+1. The "My Profile" window will appear. Click the "API Token" tab:
+
+    ![Screenshot of "API Token" tab](https://raw.githubusercontent.com/ubccr/xdmod-data/main/docs/images/api-token/api-token-tab.jpg)
+
+    **Note:** If the "API Token" tab does not appear, it means this instance of XDMoD is not configured for the Data Analytics Framework.
+
+1. If you already have an existing token, delete it:
+
+    ![Screenshot of "Delete API Token" button](https://raw.githubusercontent.com/ubccr/xdmod-data/main/docs/images/api-token/delete.jpg)
+
+1. Click the "Generate API Token" button:
+
+    ![Screenshot of "Generate API Token" button](https://raw.githubusercontent.com/ubccr/xdmod-data/main/docs/images/api-token/generate.jpg)
+
+1. Copy the token to your clipboard. Make sure to paste it somewhere for saving, as you will not be able to see the token again once you close the window:
+
+    ![Screenshot of "Copy API Token to Clipboard" button](https://raw.githubusercontent.com/ubccr/xdmod-data/main/docs/images/api-token/copy.jpg)
+
+    **Note:** If you lose your token, simply delete it and generate a new one.
+
+## Support
+For support, please see [this page](https://open.xdmod.org/support.html). If you email for support, please include the following:
+* `xdmod-data` version number, obtained by running this Python code:
+    ```
+    from xdmod_data import __version__
+    print(__version__)
+    ```
+* Operating system version.
+* A description of the problem you are experiencing.
+* Detailed steps to reproduce the problem.
+
+## License
+`xdmod-data` is released under the GNU Lesser General Public License ("LGPL") Version 3.0. See the [LICENSE](LICENSE) file for details.
+
+## Reference
+When referencing XDMoD, please cite the following publication:
+
+> Jeffrey T. Palmer, Steven M. Gallo, Thomas R. Furlani, Matthew D. Jones, Robert L. DeLeon, Joseph P. White, Nikolay Simakov, Abani K. Patra, Jeanette Sperhac, Thomas Yearke, Ryan Rathsam, Martins Innus, Cynthia D. Cornelius, James C. Browne, William L. Barth, Richard T. Evans, "Open XDMoD: A Tool for the Comprehensive Management of High-Performance Computing Resources", *Computing in Science & Engineering*, Vol 17, Issue 4, 2015, pp. 52-62. DOI:10.1109/MCSE.2015.68

README.md

@@ -2,6 +2,7 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+from importlib.metadata import version
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
@@ -12,22 +13,23 @@
 project = 'XDMoD Data Analytics Framework'
 copyright = '2023, University at Buffalo Center for Computational Research'
 author = 'University at Buffalo Center for Computational Research'
-release = '1.0'
+version = version('xdmod_data')
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
-    'sphinx_rtd_theme',
 ]
 
-# templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
+html_show_sourcelink = False
 html_theme = 'sphinx_rtd_theme'
-# html_static_path = ['_static']
+
+# -- Options for autodoc -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
+autodoc_member_order = 'bysource'

docs/conf.py

@@ -0,0 +1,26 @@
+# Developing a new version
+1. Make sure the version number is updated in `xdmod_data/__version__.py`.
+1. Create a Pull Request for the new version.
+
+# Distributing the new version to PyPI
+After the Pull Request is approved, follow these steps in the `xdmod-data` root directory:
+1. Start up a virtual environment, e.g.:
+    ```
+    $ env_dir=~/xdmod-data-build-env
+    $ python3 -m venv ${env_dir}
+    $ source ${env_dir}/bin/activate
+    ```
+1. Make sure the required packages are installed:
+    ```
+    (env) $ python3 -m pip install --upgrade pip build setuptools twine
+    ```
+1. Build the built distribution:
+    ```
+    (env) $ python3 -m build --wheel
+    ```
+1. Upload the built distribution to PyPI, e.g., for version 1.0.0-beta1:
+    ```
+    (env) $ version=1.0.0b1
+    (env) $ twine upload dist/xdmod_data-${version}-py3-none-any.whl
+    ```
+    Enter your PyPI username and password.

docs/developing.md

@@ -1,23 +1,15 @@
-.. XDMoD Data Analytics Framework documentation master file, created by
-   sphinx-quickstart on Fri Feb  3 17:15:03 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+XDMoD Data Analytics Framework |version|
+========================================
 
-XDMoD Data Analytics Framework
-==============================
-
-.. automodule:: xdmod.datawarehouse
-    :members:
-
-.. toctree::
-    :maxdepth: 2
-    :caption: Contents:
+This documents the `xdmod-data <https://github.com/ubccr/xdmod-data>`_ Python
+module.
 
+Example usage is documented through Jupyter notebooks in the
+`xdmod-notebooks <https://github.com/ubccr/xdmod-notebooks>`_ repository.
 
+.. automodule:: xdmod_data.warehouse
+   :members:
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:

docs/images/api-token/api-token-tab.jpg

@@ -0,0 +1,35 @@
+@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/images/api-token/copy.jpg

@@ -0,0 +1,4 @@
+numpy
+pandas
+plotly
+requests

docs/images/api-token/delete.jpg

@@ -0,0 +1,20 @@
+[metadata]
+name = xdmod-data
+version = attr: xdmod_data.__version__
+author = Aaron Weeden, Joseph P. White
+maintainer = Aaron Weeden, Joseph P. White
+description = Python package for XDMoD data access
+long_description = file: README.md
+long_description_content_type = text/markdown
+license_files = LICENSE
+project_urls =
+    Source Code = https://github.com/ubccr/xdmod-data
+
+[options]
+packages = find:
+python_requires = >=3
+install_requires =
+    numpy
+    pandas
+    plotly
+    requests

docs/images/api-token/generate.jpg

@@ -1,20 +1,3 @@
-from setuptools import setup, find_packages
-from xdmod.__version__ import __title__, __version__, __description__
+from setuptools import setup
 
-setup(
-    name=__title__,
-    version=__version__,
-    description=__description__,
-    license='LGPLv3',
-    author='Joseph P White',
-    author_email='jpwhite4@buffalo.edu',
-    url='https://github.com/ubccr/xdmod-python',
-    zip_safe=True,
-    packages=find_packages(),
-    install_requires=[
-        'numpy',
-        'pandas',
-        'plotly',
-        'requests',
-    ]
-)
+setup()

docs/images/api-token/my-profile.jpg

@@ -1,5 +1,5 @@
 import pytest
-import xdmod.datawarehouse as xdw
+from xdmod_data.warehouse import DataWarehouse
 import pandas
 
 VALID_XDMOD_URL = 'https://xdmod-dev.ccr.xdmod.org:9001'
@@ -101,13 +101,13 @@
 
 @pytest.fixture(scope='module')
 def dw_methods():
-    with xdw.DataWarehouse(VALID_XDMOD_URL) as dw:
+    with DataWarehouse(VALID_XDMOD_URL) as dw:
         yield __get_dw_methods(dw)
 
 
 @pytest.fixture(scope='module')
 def dw_methods_outside_runtime_context():
-    dw = xdw.DataWarehouse(VALID_XDMOD_URL)
+    dw = DataWarehouse(VALID_XDMOD_URL)
     return __get_dw_methods(dw)
 
 

docs/images/api-token/sign-in.jpg

@@ -1,5 +1,5 @@
 import pytest
-import xdmod.datawarehouse as xdw
+from xdmod_data.warehouse import DataWarehouse
 import pandas
 import numpy
 import os
@@ -10,7 +10,7 @@
 
 @pytest.fixture(scope='module')
 def valid_dw():
-    with xdw.DataWarehouse(XDMOD_URL) as dw:
+    with DataWarehouse(XDMOD_URL) as dw:
         yield dw
 
 

docs/index.rst

@@ -1,7 +1,7 @@
 import pytest
 import os
 import requests
-from xdmod.datawarehouse import DataWarehouse
+from xdmod_data.warehouse import DataWarehouse
 
 
 VALID_XDMOD_URL = 'https://xdmod.access-ci.org'

docs/make.bat

@@ -0,0 +1,2 @@
+__title__ = 'xdmod-data'
+__version__ = '1.0.0'

docs/requirements.txt

@@ -2,8 +2,8 @@
 import os
 import requests
 from urllib.parse import urlencode
-import xdmod._validator as _validator
-from xdmod.__version__ import __title__, __version__
+import xdmod_data._validator as _validator
+from xdmod_data.__version__ import __title__, __version__
 
 
 class _HttpRequester: