Doc update + get_project_by_name and pretty print

ansys/rep/client/jms/api/jms_api.py

@@ -2,7 +2,7 @@
 import logging
 import os
 import time
-from typing import List
+from typing import List, Union
 import uuid
 
 from ansys.rep.client.exceptions import REPError
@@ -53,9 +53,18 @@ def get_projects(self, **query_params):
         """Return a list of projects, optionally filtered by given query parameters"""
         return get_projects(self.client, self.url, **query_params)
 
-    def get_project(self, id=None, name=None):
+    def get_project(self, id):
         """Return a single project for given project id"""
-        return get_project(self.client, self.url, id, name)
+        return get_project(self.client, self.url, id)
+
+    def get_project_by_name(self, name, last_created=True) -> Union[Project, List[Project]]:
+        """
+        Query projects by name. If no projects are found, an empty list is returned.
+            In case of multiple projects with same name:
+             - If `last_created = True`, the last created project is returned
+             - If `last_created = False`, the full list of projects with given name is returned
+        """
+        return get_project_by_name(self.client, self.url, name, last_created)
 
     def create_project(self, project, replace=False, as_objects=True):
         """Create a new project"""
@@ -156,25 +165,37 @@ def get_projects(client, api_url, as_objects=True, **query_params) -> List[Proje
     return schema.load(data)
 
 
-def get_project(client, api_url, id=None, name=None) -> Project:
+def get_project(client, api_url, id) -> Project:
     """
     Return a single project
     """
-    params = {}
-    if name:
-        url = f"{api_url}/projects/"
-        params["name"] = name
-    else:
-        url = f"{api_url}/projects/{id}"
 
-    r = client.session.get(url, params=params)
+    url = f"{api_url}/projects/{id}"
+    r = client.session.get(url)
 
     if len(r.json()["projects"]):
         schema = ProjectSchema()
         return schema.load(r.json()["projects"][0])
     return None
 
 
+def get_project_by_name(client, api_url, name, last_created=True) -> Union[Project, List[Project]]:
+    """
+    Return a single project
+    """
+
+    params = {"name": name}
+    if last_created:
+        params["sort"] = "-creation_time"
+        params["limit"] = 1
+
+    projects = get_projects(client, api_url, **params)
+
+    if len(projects) == 1:
+        return projects[0]
+    return projects
+
+
 def create_project(client, api_url, project, replace=False, as_objects=True) -> Project:
     url = f"{api_url}/projects/"
 

ansys/rep/client/jms/resource/base.py

@@ -55,4 +55,24 @@ def __repr__(self):
         )
 
     def __str__(self):
-        return json.dumps(self.Meta.schema(many=False).dump(self), indent=2)
+
+        # Ideally we'd simply do
+        #   return json.dumps(self.Meta.schema(many=False).dump(self), indent=2)
+        # However the schema.dump() function (rightfully) ignores fields marked as load_only.
+        #
+        # Therefore we have to manually iterate over all fields
+
+        schema = self.Meta.schema(many=False)
+        dict_repr = schema.dict_class()
+        for attr_name, field_obj in schema.fields.items():
+            value = missing
+            try:
+                value = field_obj.serialize(attr_name, self, accessor=schema.get_attribute)
+            except:
+                pass
+            if value is missing:
+                continue
+            key = field_obj.data_key if field_obj.data_key is not None else attr_name
+            dict_repr[key] = value
+
+        return json.dumps(dict_repr, indent=2)

doc/source/conf.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # Sphinx documentation configuration file
 from datetime import datetime
 import os
@@ -11,16 +9,22 @@
 
 sys.path.append(os.path.abspath(os.path.dirname(__file__)))
 
+# -- Project information -----------------------------------------------------
+
+# General information about the project.
+project = "Ansys pyrep"
+copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
+author = __company__
+
+# The short X.Y version
+release = version = __version__
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
 
-# -- General job_definition ------------------------------------------------
-
-# If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
-
+# -- General configuration ---------------------------------------------------
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
@@ -62,23 +66,9 @@
 # The master toctree document.
 master_doc = "index"
 
-# General information about the project.
-project = "Ansys pyrep"
-copyright = f"(c) {datetime.now().year} {__company__}. All rights reserved"
-author = __company__
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = __external_version__
-# The full version, including alpha/beta/rc tags.
-release = __external_version__
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-# language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -121,106 +111,45 @@
 
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
 html_theme = "ansys_sphinx_theme"
 
 # only for  sphinx_rtd_theme
 html_theme_options = {
-    "github_url": "[https://github.com/pyansys/pyrep",
+    "github_url": "https://github.com/pyansys/pyrep",
     "show_prev_next": False,
     "show_breadcrumbs": True,
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
     ],
-    #'canonical_url': '',
-    #'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
-    #'logo_only': False,
-    # "display_version": True,
-    # "prev_next_buttons_location": "bottom",
-    #'style_external_links': False,
-    #'vcs_pageview_mode': '',
-    #'style_nav_header_background': 'white',
-    # Toc options
     "collapse_navigation": True,
-    # "sticky_navigation": True,
     "navigation_depth": 4,
-    # "includehidden": True,
-    # "titles_only": False,
 }
 
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-# html_title = None
-
 # A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = html_title = "pyrep"
+html_short_title = html_title = "PyREP"
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 html_logo = logo
 
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-# html_favicon = None
+# Favicon
+html_favicon = "favicon.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-# html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-# html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-# html_additional_pages = {}
-
-# If false, no module index is generated.
-# html_domain_indices = True
-
-# If false, no index is generated.
-# html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-# html_split_index = False
-
 # If true, links to the reST sources are added to the pages.
 html_show_sourcelink = False
 
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-# html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-# html_show_copyright = True
-
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 # html_use_opensearch = ''
 
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-# html_file_suffix = None
-
 # Output file base name for HTML help builder.
-htmlhelp_basename = "REPclientdoc"
+htmlhelp_basename = "pyrepdoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -242,7 +171,7 @@
         "index",
         "ansys-rep-client.tex",
         "REP Python Client Documentation",
-        "ANSYS Switzerland Gmbh",
+        author,
         "manual",
     ),
 ]
@@ -343,9 +272,9 @@
         secured?returnurl=/Views/Secured/corp/v231/en/rep_ug/%s.html""",
         "ANSYS Help - ",
     ),
-    "ansys_rep_tutorial": (
+    "ansys_dcs_tutorial": (
         """https://ansyshelp.ansys.com/account/
-        secured?returnurl=/Views/Secured/corp/v231/en/rep_tut/%s.html""",
+        secured?returnurl=/Views/Secured/corp/v231/en/dcs_tut/%s.html""",
         "REP Tutorial - ",
     ),
 }

doc/source/index.rst

@@ -1,28 +1,25 @@
-Ansys REP Python Client
-=============================
+PyREP Documentation |version|
+=================================
+
+.. toctree::
+    :hidden:
+    :maxdepth: 3
+
+    install
+    quickstart
+    examples/index
+    api/index
+
+Introduction
+------------
 
 Ansys Remote Execution Platform (REP) is a family of applications that enables you to distribute, 
 manage and solve simulations on a variety of compute resources. 
-As part of this, the Job Management Service (JMS) facilitates the robust solution of 
-tens of thousands of design points spread across clusters, networks and operating systems.
-
 
-**ansys-rep-client** brings Ansys REP to your Python application. 
+``ansys-rep-client`` brings Ansys REP to your Python application. 
 Wrapping around the REP REST APIs, it allows you to:
 
 * create new projects and modify existing ones
 * monitor and manage jobs
 * run your own design exploration algorithms 
-* retrieve simulation results
-
-User Guide
-===========
-
-.. toctree::
-    :maxdepth: 2
-
-    install
-    quickstart
-    examples/index
-    api/index
-    changelog/index
+* retrieve simulation results

doc/source/install.rst

@@ -5,40 +5,37 @@ Installation
 
 Make sure you have ``Python 3`` and that the expected version is available from your command line. You can check this by running:
 
-.. parsed-literal::
+.. code:: 
 
-    $ python --version
+    python --version
 
 If you do not have Python, please install the latest 3.x version from `python.org <https://python.org>`_.
 
 Additionally, make sure you have ``pip`` available. You can check this by running:
 
-.. parsed-literal::
+.. code:: 
 
-    $ pip --version
+    pip --version
 
 If pip isn't already installed, please refer to the `Installing Packages Tutorial <https://packaging.python.org/tutorials/installing-packages/>`_ from the Python Packaging Authority.
 
 
-Installing ``ansys-dcs-client`` is as simple as, on Windows:
+As long as PyREP is a private PyAnsys package not published to PyPI yet, you can execute
 
-.. parsed-literal::
-
-    $ pip install "%AWP_ROOT\ |version_no_dots|\ %\\dcs\\share\\python_client\\ansys_dcs_client-\ |client_version|\ -py3-none-any.whl"
-
-on Linux:
-
-.. parsed-literal::
-
-    $ pip install /usr/ansys_inc/v\ |version_no_dots|\ /dcs/share/python_client/ansys_dcs_client-\ |client_version|\ -py3-none-any.whl
+.. code:: 
 
+    python -m pip install git+https://github.com/pyansys/pyrep
 
 The following dependencies are automatically installed through ``pip`` (if not already available):
 
+- cachetools_
 - requests_
 - marshmallow_
 - marshmallow_oneofschema_
+- python-keycloak_
 
 .. _requests: https://pypi.org/project/requests/
 .. _marshmallow: https://pypi.org/project/marshmallow/
 .. _marshmallow_oneofschema: https://pypi.org/project/marshmallow-oneofschema/
+.. _cachetools: https://pypi.org/project/cachetools/
+.. _python-keycloak: https://pypi.org/project/python-keycloak/