Merge branch 'main' into release/0.2

.pre-commit-config.yaml

@@ -1,15 +1,15 @@
 repos:
 
 - repo: https://github.com/psf/black
-  rev: 22.12.0  # IF VERSION CHANGES --> MODIFY "blacken-docs" MANUALLY AS WELL!!
+  rev: 23.1.0  # IF VERSION CHANGES --> MODIFY "blacken-docs" MANUALLY AS WELL!!
   hooks:
   - id: black
 
 - repo: https://github.com/adamchainz/blacken-docs
   rev: 1.13.0
   hooks:
   - id: blacken-docs
-    additional_dependencies: [black==22.12.0]
+    additional_dependencies: [black==23.1.0]
 
 - repo: https://github.com/pycqa/isort
   rev: 5.12.0

AUTHORS.md

@@ -0,0 +1,16 @@
+# Authors
+
+## Project Lead
+
+* [Roberto Pastor](https://github.com/RobPasMue)
+
+## Contributors
+
+* [Jonah Boling](https://github.com/jonahrb)
+* [Matteo Bini](https://github.com/b-matteo)
+* [Chad Queen](https://github.com/chadqueen)
+* [Revathy Venugopal](https://github.com/Revathyvenugopal162)
+* [Maxime Rey](https://github.com/MaxJPRey)
+* [Alexander Kaszynski](https://github.com/akaszynski)
+* [Jorge Martínez](https://github.com/jorgepiloto)
+* [Alejandro Fernández](https://github.com/AlejandroFernandezLuces)

CONTRIBUTING.md

@@ -1,2 +1,16 @@
-# Contributing 
+# Contributing
 
+We absolutely welcome any code contributions and we hope that this
+guide will facilitate an understanding of the PyGeometry code
+repository. It is important to note that while the PyGeometry software
+package is maintained by ANSYS and any submissions will be reviewed
+thoroughly before merging, we still seek to foster a community that can
+support user questions and develop new features to make this software
+a useful tool for all users. As such, we welcome and encourage any
+questions or submissions to this repository.
+
+For contributing to this project, please refer to the [PyAnsys Developer's Guide].
+Further information about contributing to PyGeometry can be found in [Contributing].
+
+[PyAnsys Developer's Guide]: https://dev.docs.pyansys.com/index.html
+[Contributing]: https://geometry.docs.pyansys.com/dev/contributing.html

README.rst

@@ -119,7 +119,14 @@ If you want to change the defaults, modify the following environment variables:
    export ANSRV_GEO_HOST=127.0.0.1
    export ANSRV_GEO_PORT=50051
 
-**On Windows**
+**On Windows Powershell**
+
+.. code::
+
+   $env:ANSRV_GEO_HOST="127.0.0.1"
+   $env:ANSRV_GEO_PORT=50051
+
+**On Windows CMD**
 
 .. code::
 
@@ -182,6 +189,12 @@ To install PyGeometry in developer mode, perform these steps:
 
       git clone https://github.com/pyansys/pygeometry
 
+#. Access the ``pygeometry`` directory where the repository has been cloned:
+
+   .. code:: bash
+
+      cd pygeometry
+
 #. Create a clean Python virtual environment and activate it:
 
    .. code:: bash
@@ -204,18 +217,21 @@ To install PyGeometry in developer mode, perform these steps:
 
       python -m pip install -U pip tox
 
-
 #. Install the project in editable mode:
 
    .. code:: bash
-    
-      python -m pip install ansys-geometry-core
-        
-#. Verify your development installation by running:
+      
+      # Install the minimum requirements
+      python -m pip install -e .
 
-   .. code:: bash
-        
-      tox
+      # Install the minimum + tests requirements
+      python -m pip install -e .[tests]
+
+      # Install the minimum + doc requirements
+      python -m pip install -e .[doc]
+
+      # Install the all requirements
+      python -m pip install -e .[tests,doc]
 
 Install in offline mode
 ^^^^^^^^^^^^^^^^^^^^^^^

doc/source/conf.py

@@ -22,7 +22,7 @@
 project = "ansys-geometry-core"
 copyright = f"(c) {datetime.now().year} ANSYS, Inc. All rights reserved"
 author = "ANSYS, Inc."
-release = version = "0.2.0"
+release = version = __version__
 cname = os.getenv("DOCUMENTATION_CNAME", default="nocname.com")
 
 # Select desired logo, theme, and declare the html title

doc/source/contributing.rst

@@ -43,7 +43,7 @@ Documentation for the latest stable release of PyGeometry is hosted at
 `PyGeometry Documentation <https://geometry.docs.pyansys.com>`_.
 
 Documentation for the latest development version, which tracks the
-``main`` branch, is hosted at `Development PyGeometry Documentation <https://dev.geometry.docs.pyansys.com/>`_.
+``main`` branch, is hosted at `Development PyGeometry Documentation <https://geometry.docs.pyansys.com/dev/>`_.
 This version is automatically kept up to date via GitHub actions.
 
 Code style

doc/source/getting_started/docker.rst

@@ -1,29 +1,89 @@
+.. _ref_docker:
+
 Geometry service using Docker
 =============================
 
+Docker
+------
+
+Ensure that the machine in which the Geometry service should run has Docker installed. Otherwise,
+please install `Docker Engine <https://docs.docker.com/engine/install/>`_ from the previous link.
+
+.. caution::
+    At the moment, the Geometry service backend is only delivered as a Windows Docker container.
+    As such, this container only runs on a Windows machine. Furthermore, it has also been observed
+    that certain Docker Desktop versions for Windows are not properly configured for running Windows
+    Docker containers. Refer to our section
+    :ref:`Running the Geometry service Windows Docker container <ref_docker_windows>` for further details.
+
+.. _ref_docker_windows:
+
+Running the Geometry service Windows Docker container
+-----------------------------------------------------
+
+For running the Windows Docker container of the Geometry service, please ensure that
+you follow the upcoming steps when installing Docker:
+
+#. Install `Docker Desktop 4.13.1 <https://docs.docker.com/desktop/release-notes/#4131>`_ **or below**.
+   It has been observed that newer versions present problems when running Windows Docker containers.
+
+#. When prompted for ``Use WSL2 instead of Hyper-V (recommended)``, **deselect this option**.
+
+#. Once the installation process finishes, open up Docker Desktop.
+
+#. On ``Settings >> Software updates``, deselect ``Automatically check for updates``. Then, ``Apply & restart``.
+
+#. On the Windows taskbar, go to the ``Show hidden icons`` section, right click on the Docker Desktop app and
+   select ``Switch to Windows containers...``.
+
+At this point, your Docker engine will support running Windows Docker containers. Next step will involve downloading
+the Geometry service Windows Docker image.
+
 Install the PyGeometry image
 ----------------------------
 
+Once you have Docker installed on your machine, the next steps involve pulling down the Geometry service
+Docker container.
+
 #. Using your GitHub credentials, download the Docker image from the `pygeometry <https://github.com/pyansys/pygeometry>`_ repository.
+
 #. If you have Docker installed, use a GitHub personal access token (PAT) with packages read permission to authorize Docker 
    to access this repository. For more information,
    see `creating a personal access token <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_.
 
 #. Save the token to a file:
 
-   .. code:: bash
+    .. code-block:: bash
 
-      echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX > GH_TOKEN.txt
+        echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX > GH_TOKEN.txt
 
 #. Authorize Docker to access the repository:
 
-   .. code:: bash
+.. tab-set:: 
 
-      GH_USERNAME=<my-github-username>
-      cat GH_TOKEN.txt | docker login docker.pkg.github.com -u $GH_USERNAME --password-stdin
+    .. tab-item:: Linux/Mac
+
+        .. code-block:: bash
+
+            GH_USERNAME=<my-github-username>
+            cat GH_TOKEN.txt | docker login ghcr.io -u $GH_USERNAME --password-stdin
+
+    .. tab-item:: Powershell
+
+        .. code-block:: bash
+
+            $env:GH_USERNAME=<my-github-username>
+            cat GH_TOKEN.txt | docker login ghcr.io -u $env:GH_USERNAME --password-stdin
+
+    .. tab-item:: Windows CMD
+
+        .. code-block:: bash
+
+            SET GH_USERNAME=<my-github-username>
+            type GH_TOKEN.txt | docker login ghcr.io -u %GH_USERNAME% --password-stdin
 
-#. Pull the Geometry service locally using Docker with:
 
+#. Pull the Geometry service locally using Docker with:
 
    .. code:: bash
 
@@ -72,7 +132,15 @@ Depending on the mechanism chosen to launch the Geometry service, you can set th
                     export ANSRV_GEO_ENABLE_TRACE=0
                     export ANSRV_GEO_LOG_LEVEL=2
 
-            .. tab-item:: Windows
+            .. tab-item:: Powershell
+
+                .. code-block:: bash
+
+                    $env:ANSRV_GEO_LICENSE_SERVER="127.0.0.1"
+                    $env:ANSRV_GEO_ENABLE_TRACE=0
+                    $env:ANSRV_GEO_LOG_LEVEL=2
+
+            .. tab-item:: Windows CMD
 
                 .. code-block:: bash
 
@@ -150,7 +218,14 @@ If you want to change the defaults, modify environment variables and the
                     export ANSRV_GEO_HOST=127.0.0.1
                     export ANSRV_GEO_PORT=50051
 
-            .. tab-item:: Windows
+            .. tab-item:: Powershell
+
+                .. code-block:: bash
+
+                    $env:ANSRV_GEO_HOST="127.0.0.1"
+                    $env:ANSRV_GEO_PORT=50051
+
+            .. tab-item:: Windows CMD
 
                 .. code-block:: bash
 

doc/source/getting_started/index.rst

@@ -7,6 +7,11 @@ To use PyGeometry, you must have a local installation of `Docker <https://docs.d
 To start the service locally, you must be `authenticated to ghcr.io
 <https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry>`_.
 
+.. caution::
+   PyGeometry is a client library that works with a Geometry service backend. This service is distributed
+   as a Docker container. At the moment, there is only a Windows Docker container version available for this
+   service. For more information please refer to the :ref:`Geometry service using Docker <ref_docker>` section.
+
 .. toctree::
 
    docker

pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "ansys-api-geometry==0.2.0",
+    "ansys-api-geometry==0.2.1",
     "beartype>=0.11.0",
     "google-api-python-client>=1.7.11",
     "googleapis-common-protos>=1.52.0",
@@ -43,11 +43,11 @@ dependencies = [
 [project.optional-dependencies]
 tests = [
     "beartype==0.12.0",
-    "google-api-python-client==2.75.0",
+    "google-api-python-client==2.77.0",
     "googleapis-common-protos==1.58.0",
     "grpcio==1.50.0",
     "grpcio-health-checking==1.48.2",
-    "numpy==1.24.1",
+    "numpy==1.24.2",
     "Pint==0.20.1",
     "protobuf==3.20.3",
     "pyvista==0.37.0",
@@ -57,10 +57,10 @@ tests = [
     "docker==6.0.1",
     "pytest==7.2.1",
     "pytest-cov==4.0.0",
-    "pytest-pyvista==0.1.5",
+    "pytest-pyvista==0.1.6",
 ]
 doc = [
-    "ansys-sphinx-theme==0.8.1",
+    "ansys-sphinx-theme==0.8.2",
     "ipyvtklink==0.2.3",
     "jupyter_sphinx==0.4.0",
     "jupytext==1.14.4",

src/ansys/geometry/core/connection/launcher.py

@@ -2,7 +2,11 @@
 from beartype.typing import TYPE_CHECKING, Optional
 
 from ansys.geometry.core.connection.defaults import DEFAULT_PORT
-from ansys.geometry.core.connection.local_instance import GeometryContainers, LocalDockerInstance
+from ansys.geometry.core.connection.local_instance import (
+    _HAS_DOCKER,
+    GeometryContainers,
+    LocalDockerInstance,
+)
 from ansys.geometry.core.logger import LOG as logger
 from ansys.geometry.core.misc import check_type
 
@@ -41,12 +45,12 @@ def launch_modeler() -> "Modeler":
 
     # Start PyGeometry with PyPIM if the environment is configured for it
     # and a directive on how to launch it was not passed.
-    if pypim.is_configured():
+    if _HAS_PIM and pypim.is_configured():
         logger.info("Starting Geometry service remotely. The startup configuration is ignored.")
         return launch_remote_modeler()
 
     # Otherwise, we are in the "local Docker Container" scenario
-    if LocalDockerInstance.is_docker_installed():
+    if _HAS_DOCKER and LocalDockerInstance.is_docker_installed():
         logger.info("Starting Geometry service locally from Docker container.")
         return launch_local_modeler()
 
@@ -142,6 +146,9 @@ def launch_local_modeler(
 
     from ansys.geometry.core.modeler import Modeler
 
+    if not _HAS_DOCKER:  # pragma: no cover
+        raise ModuleNotFoundError("The package 'docker' is required to use this function.")
+
     # Call the LocalDockerInstance ctor.
     local_instance = LocalDockerInstance(
         port=port,

src/ansys/geometry/core/connection/local_instance.py

@@ -176,7 +176,7 @@ def _check_port_availability(self, port: int) -> Tuple[bool, Optional["Container
         """
         # First, check if there is a container already running at that port
         for cont in self.docker_client().containers.list():
-            for (_, ports_shared) in cont.attrs["NetworkSettings"]["Ports"].items():
+            for _, ports_shared in cont.attrs["NetworkSettings"]["Ports"].items():
                 for port_shared in ports_shared:
                     if int(port_shared["HostPort"]) == port:
                         logger.warning(f"Service already running at port {port}...")