{"id":6983,"library":"ansys-tools-common","title":"Ansys Common Tools","description":"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.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/ansys/ansys-tools-common","tags":["ansys","tools","utility","pyansys","engineering","logging","download"],"install":[{"cmd":"pip install ansys-tools-common","lang":"bash","label":"Base installation"},{"cmd":"pip install ansys-tools-common[launcher]","lang":"bash","label":"With gRPC launcher support"}],"dependencies":[{"reason":"Required for gRPC launcher functionality.","package":"grpcio","optional":true},{"reason":"Required for gRPC launcher functionality.","package":"grpcio-tools","optional":true}],"imports":[{"symbol":"generate_self_signed_certificates","correct":"from ansys.tools.common.certs import generate_self_signed_certificates"},{"symbol":"download_file","correct":"from ansys.tools.common.downloads import download_file"},{"symbol":"AnsysNotification","correct":"from ansys.tools.common.misc import AnsysNotification"},{"note":"Launcher classes are in a specific submodule; direct import from `ansys.tools.common` is incorrect.","wrong":"from ansys.tools.common import GrpcServerLauncher","symbol":"GrpcServerLauncher","correct":"from ansys.tools.common.launcher import GrpcServerLauncher"}],"quickstart":{"code":"import logging\nimport tempfile\nimport os\nfrom ansys.tools.common.misc import AnsysNotification\n\n# Configure logging to see AnsysNotification messages\nlogging.basicConfig(level=logging.INFO, format='%(levelname)s:%(name)s:%(message)s')\n\n# Example 1: Using AnsysNotification (new in v0.5.0)\nnotification = AnsysNotification(\n    title=\"Example Message\",\n    message=\"This is a test notification from ansys-tools-common.\",\n    tag=\"INFO\"\n)\nnotification.display()\n\n# Example 2: Downloading a file\n# Note: This is a placeholder for a real download URL\nexample_url = os.environ.get('EXAMPLE_DOWNLOAD_URL', 'https://www.ansys.com/static/assets/ansys-logo-full-color.svg')\nif example_url == 'https://www.ansys.com/static/assets/ansys-logo-full-color.svg':\n    print(\"Using placeholder URL. Provide a real URL for full functionality.\")\n\nwith tempfile.TemporaryDirectory() as tmpdir:\n    from ansys.tools.common.downloads import download_file\n    downloaded_path = download_file(url=example_url, directory=tmpdir)\n    print(f\"File downloaded to: {downloaded_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Add `logging.basicConfig(level=logging.INFO)` at the start of your script or configure your logging system appropriately before displaying notifications.","message":"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)`).","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Always use fully qualified imports like `from ansys.tools.common.misc import AnsysNotification` instead of `from ansys.tools.common import AnsysNotification`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Install the library with the necessary extras: `pip install ansys-tools-common[launcher]`.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your Python environment is running version 3.10 or later and less than 4.0.","message":"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).","severity":"breaking","affected_versions":">=0.4.0 (check specific version changes, 3.10+ requirement is stated for 0.5.0)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library with the `launcher` extra: `pip install ansys-tools-common[launcher]`.","cause":"Attempting to use gRPC launcher functionality without installing the optional dependencies.","error":"ModuleNotFoundError: No module named 'ansys.tools.common.launcher'"},{"fix":"Call the `.display()` method on the `AnsysNotification` instance: `notification.display()`.","cause":"Trying to directly call an `AnsysNotification` instance like a function instead of using its `.display()` method.","error":"TypeError: 'AnsysNotification' object is not callable"},{"fix":"Import the class from its specific submodule, e.g., `from ansys.tools.common.misc import AnsysNotification`.","cause":"Incorrectly importing a class directly from the top-level `ansys.tools.common` package when it resides in a submodule.","error":"AttributeError: module 'ansys.tools.common' has no attribute 'AnsysNotification'"},{"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)`.","cause":"The `download_file` function was called with a directory path that does not exist, and `make_directory` was not set to `True`.","error":"RuntimeError: Cannot download to a non-existent directory without `make_directory=True`."}]}