Ansys Common Tools

0.5.0 · active · verified Thu Apr 16

Ansys Common Tools is a Python library providing a set of utilities and helper functions designed for use across various PyAnsys libraries. It includes tools for certificate management, file downloads, error handling, gRPC server launching, miscellaneous helpers, and versioning. The current version is 0.5.0, and it follows a regular, feature-driven release cadence.

Common errors

```
ModuleNotFoundError: No module named 'ansys.tools.common.launcher'
```
cause Attempting to use gRPC launcher functionality without installing the optional dependencies.

fix Install the library with the `launcher` extra: `pip install ansys-tools-common[launcher]`.
```
TypeError: 'AnsysNotification' object is not callable
```
cause Trying to directly call an `AnsysNotification` instance like a function instead of using its `.display()` method.

fix Call the `.display()` method on the `AnsysNotification` instance: `notification.display()`.
```
AttributeError: module 'ansys.tools.common' has no attribute 'AnsysNotification'
```
cause Incorrectly importing a class directly from the top-level `ansys.tools.common` package when it resides in a submodule.

fix Import the class from its specific submodule, e.g., `from ansys.tools.common.misc import AnsysNotification`.
```
RuntimeError: Cannot download to a non-existent directory without `make_directory=True`.
```
cause The `download_file` function was called with a directory path that does not exist, and `make_directory` was not set to `True`.

fix Ensure the target directory exists before calling `download_file`, or pass `make_directory=True` to the function call, e.g., `download_file(url, directory='non_existent_path', make_directory=True)`.

Warnings

gotcha AnsysNotification utilizes Python's standard logging module. If you don't see notifications, ensure you have configured a logger to display messages at or above the notification's severity level (e.g., `logging.basicConfig(level=logging.INFO)`).
Fix: Add `logging.basicConfig(level=logging.INFO)` at the start of your script or configure your logging system appropriately before displaying notifications.
gotcha The library is organized into distinct submodules (e.g., `certs`, `downloads`, `launcher`). You must import specific classes or functions from their respective submodules, not directly from the top-level `ansys.tools.common` package.
Fix: Always use fully qualified imports like `from ansys.tools.common.misc import AnsysNotification` instead of `from ansys.tools.common import AnsysNotification`.
gotcha Some functionalities, like the gRPC server launcher, require optional dependencies (`grpcio`, `grpcio-tools`). Attempting to use these features without installing the `[launcher]` extra will result in a `ModuleNotFoundError`.
Fix: Install the library with the necessary extras: `pip install ansys-tools-common[launcher]`.
breaking Python version compatibility has been narrowed. `ansys-tools-common` now requires Python 3.10 or newer, and is not compatible with Python 4.x (if/when it exists).
Fix: Ensure your Python environment is running version 3.10 or later and less than 4.0.

Install

pip install ansys-tools-common Base installation
pip install ansys-tools-common[launcher] With gRPC launcher support

Imports

generate_self_signed_certificates

from ansys.tools.common.certs import generate_self_signed_certificates

download_file

from ansys.tools.common.downloads import download_file

AnsysNotification

from ansys.tools.common.misc import AnsysNotification

GrpcServerLauncher
wrong:
```
from ansys.tools.common import GrpcServerLauncher
```
correct:
```
from ansys.tools.common.launcher import GrpcServerLauncher
```
Launcher classes are in a specific submodule; direct import from `ansys.tools.common` is incorrect.

Quickstart

This quickstart demonstrates how to use the `AnsysNotification` class (introduced in v0.5.0) and the `download_file` utility. Ensure your logging is configured to view notifications. For the download example, a placeholder URL is used; replace it with a valid URL for testing actual file downloads.

import logging
import tempfile
import os
from ansys.tools.common.misc import AnsysNotification

# Configure logging to see AnsysNotification messages
logging.basicConfig(level=logging.INFO, format='%(levelname)s:%(name)s:%(message)s')

# Example 1: Using AnsysNotification (new in v0.5.0)
notification = AnsysNotification(
    title="Example Message",
    message="This is a test notification from ansys-tools-common.",
    tag="INFO"
)
notification.display()

# Example 2: Downloading a file
# Note: This is a placeholder for a real download URL
example_url = os.environ.get('EXAMPLE_DOWNLOAD_URL', 'https://www.ansys.com/static/assets/ansys-logo-full-color.svg')
if example_url == 'https://www.ansys.com/static/assets/ansys-logo-full-color.svg':
    print("Using placeholder URL. Provide a real URL for full functionality.")

with tempfile.TemporaryDirectory() as tmpdir:
    from ansys.tools.common.downloads import download_file
    downloaded_path = download_file(url=example_url, directory=tmpdir)
    print(f"File downloaded to: {downloaded_path}")

view raw JSON →