Metadata-Version: 2.4
Name: ansys-dynamicreporting-core
Version: 1.0.0rc1
Summary: Python interface to Ansys Dynamic Reporting
Project-URL: homepage, https://github.com/ansys/pydynamicreporting
Project-URL: documentation, https://dynamicreporting.docs.pyansys.com/
Project-URL: changelog, https://github.com/ansys/pydynamicreporting/blob/main/CHANGELOG.md
Project-URL: repository, https://github.com/ansys/pydynamicreporting
Project-URL: bug_tracker, https://github.com/ansys/pydynamicreporting/issues
Project-URL: ci, https://github.com/ansys/pydynamicreporting/actions
Author-email: "ANSYS, Inc." <pyansys.core@ansys.com>, Ansys ADR Team <adrteam@ansys.com>
Maintainer-email: "ANSYS, Inc." <pyansys.core@ansys.com>, Ansys ADR Team <adrteam@ansys.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ansys,dynamicreporting,pyansys,pydynamicreporting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.10
Requires-Dist: bleach>=6.2.0
Requires-Dist: django-guardian<4.0.0,>=2.4.0
Requires-Dist: django<6.0.0,>=4.2.27
Requires-Dist: djangorestframework<3.18.0,>=3.15.2
Requires-Dist: docker>=7.1.0
Requires-Dist: lark<1.3.0,>=1.2.2
Requires-Dist: numpy<2.0.0,>=1.26.4; python_version < '3.13'
Requires-Dist: numpy<3.0.0,>=2.0.0; python_version >= '3.13'
Requires-Dist: pandas<3.0.0,>=2.2.2
Requires-Dist: pillow>=9.3.0
Requires-Dist: playwright==1.60.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: psycopg[binary]<3.3.0,>=3.2.6
Requires-Dist: pypng>=0.20220715.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: python-pptx<2.0.0,>=1.0.2
Requires-Dist: pytz>=2021.3
Requires-Dist: qtpy<2.5.0,>=2.4.3
Requires-Dist: requests>=2.32
Requires-Dist: statsmodels<0.15.0,>=0.14.2
Requires-Dist: tzlocal<6.0,>=5.3.1
Requires-Dist: urllib3<3.0.0,>=2.6.3
Provides-Extra: dev
Requires-Dist: codespell; extra == 'dev'
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: ipdb; extra == 'dev'
Requires-Dist: pip; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: uv; extra == 'dev'
Provides-Extra: doc
Requires-Dist: ansys-sphinx-theme; extra == 'doc'
Requires-Dist: docutils>=0.21; extra == 'doc'
Requires-Dist: numpydoc; extra == 'doc'
Requires-Dist: sphinx; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-gallery; extra == 'doc'
Provides-Extra: test
Requires-Dist: ansys-dpf-core==0.16.1; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pyvista==0.48.4; extra == 'test'
Requires-Dist: vtk==9.6.2; extra == 'test'
Description-Content-Type: text/x-rst

PyDynamicReporting
==================

|pyansys| |python| |pypi| |GH-CI| |cov| |MIT| |black|

.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?labelColor=black&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
   :target: https://docs.pyansys.com/
   :alt: PyAnsys

.. |python| image:: https://img.shields.io/pypi/pyversions/ansys-dynamicreporting-core?logo=pypi
   :target: https://pypi.org/project/ansys-dynamicreporting-core/
   :alt: Python

.. |pypi| image:: https://img.shields.io/pypi/v/ansys-dynamicreporting-core.svg?logo=python&logoColor=white
   :target: https://pypi.org/project/ansys-dynamicreporting-core
   :alt: PyPI

.. |GH-CI| image:: https://github.com/ansys/pydynamicreporting/actions/workflows/ci_cd.yml/badge.svg?branch=main
   :target: https://github.com/ansys/pydynamicreporting/actions?query=branch%3Amain
   :alt: GH-CI

.. |cov| image:: https://codecov.io/gh/ansys/pydynamicreporting/graph/badge.svg?token=WCAK7QRLR3
   :target: https://codecov.io/gh/ansys/pydynamicreporting
   :alt: codecov

.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: MIT

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
   :target: https://github.com/psf/black
   :alt: Black

.. _Nexus: https://nexusdemo.ensight.com/docs/html/Nexus.html

Overview
--------
PyDynamicReporting is the Python client library for Ansys Dynamic Reporting,
previously documented as `Nexus`_. Ansys Dynamic Reporting is a service for
pushing items of many types, including images, text, 3D scenes, and tables,
into a database, where you can keep them organized and create dynamic reports
from them. When you use PyDynamicReporting to connect to an instance of
Ansys Dynamic Reporting, you have a Pythonic way of accessing all capabilities
of Ansys Dynamic Reporting.

Documentation and issues
------------------------
Documentation for the latest stable release of PyDynamicReporting is hosted at
`PyDynamicReporting documentation <https://dynamicreporting.docs.pyansys.com/version/stable/>`_.

In the upper right corner of the documentation's title bar, there is an option
for switching from viewing the documentation for the latest stable release
to viewing the documentation for the development version or previously
released versions.

You can also `view <https://cheatsheets.docs.pyansys.com/pydynamicreporting_cheat_sheet.png>`_
or `download <https://cheatsheets.docs.pyansys.com/pydynamicreporting_cheat_sheet.pdf>`_
the PyDynamicReporting cheat sheet. This one-page reference provides syntax
rules and commands for using PyDynamicReporting.

On the `PyDynamicReporting Issues <https://github.com/ansys/pydynamicreporting/issues>`_
page, you can create issues to report bugs and request new features. On the
`Discussions <https://discuss.ansys.com/>`_ page on the Ansys Developer portal,
you can post questions, share ideas, and get community feedback.

To reach the project support team, email
`pyansys.core@ansys.com <pyansys.core@ansys.com>`_.

Installation
------------
The ``pydynamicreporting`` package supports Python 3.10 through 3.13 on
Windows and Linux. It is currently available on
`PyPI <https://pypi.org/project/ansys-dynamicreporting-core/>`_.

For the base client package, run:

.. code::

   pip install ansys-dynamicreporting-core

Developer installation
^^^^^^^^^^^^^^^^^^^^^^
This project uses `uv <https://github.com/astral-sh/uv>`_ for fast dependency
management and virtual environment handling. To set up a development
environment:

**Prerequisites**

Install `uv` by following the `official installation guide <https://docs.astral.sh/uv/getting-started/installation/>`_.

You'll also need `make`:

.. code::

   # On Windows, install using chocolatey:
   choco install make

   # On Linux, make is usually pre-installed. If not, install via:
   sudo apt-get install build-essential  # Ubuntu/Debian
   sudo yum groupinstall "Development Tools"  # RHEL/CentOS/Fedora

**Clone and Install**

.. code::

   git clone https://github.com/ansys/pydynamicreporting
   cd pydynamicreporting
   make install

The ``make install`` command does the following:

- Synchronizes dependencies from ``uv.lock`` (includes all optional extras)
- Creates a ``.venv`` virtual environment automatically
- Installs the package in editable mode

This creates an "editable" installation that lets you develop and test
PyDynamicReporting simultaneously.

**Developer workflow note**

After making changes, run the pre-commit hooks (via ``uv``) before committing.
Otherwise, the code-style CI check will fail.

.. code::

   make check

**Available Make Commands**

The Makefile provides several useful commands:

.. code::

   make check        # Run code quality checks (pre-commit hooks)
   make version      # Display the current project version
   make build        # Build source distribution and wheel
   make check-dist   # Validate built artifacts
   make test         # Run the full test suite with coverage
   make smoketest    # Quick import test
   make docs         # Build documentation
   make clean        # Remove build artifacts and caches

**Running Tests**

To run tests with coverage reporting:

.. code::

   make test

For a quick sanity check:

.. code::

   make smoketest

**Updating Dependencies**

If you see an error like ``The lockfile at `uv.lock` needs to be updated``,
run the following commands to update the lock file:

.. code::

   uv sync --upgrade --all-extras
   uv lock --upgrade

Then make sure to commit the updated ``uv.lock`` file.
This ensures your local environment is synchronized with the latest dependency
constraints.

**Resolving CI Security Scan Errors**

If CI reports a ``Security Scan`` error, first activate the virtual
environment and then refresh the environment and lock file:

.. code::

  # Windows PowerShell
  .\.venv\Scripts\Activate.ps1

  # Linux/macOS
  source .venv/bin/activate

  uv sync --upgrade --all-extras
  uv lock --upgrade

After these commands finish, commit the updated ``uv.lock`` file.

For serverless compatibility work, keep the base dependency set broad enough to
span the supported ADR product lines and place release-specific pins in
``constraints/``.

Local GitHub Actions
^^^^^^^^^^^^^^^^^^^^
To run GitHub Actions on your local desktop, install the
`act <https://github.com/nektos/act#readme>`_ package:

.. code::

   choco install act-cli  # Windows
   # or: brew install act  # macOS/Linux with Homebrew

To run a specific job from the CI/CD workflow, use:

.. code::

   act -W '.github/workflows/ci_cd.yml' -j style --bind      # Run code style checks
   act -W '.github/workflows/ci_cd.yml' -j smoketest --bind  # Run smoke tests

**Note**: Deploy and upload steps are guarded with ``if: ${{ !env.ACT }}`` to
prevent them from running locally. Only build and validation steps will
execute with ``act``.

Creating a Release
------------------

This project now uses **tag-driven releases** and **dynamic versions** powered
by ``hatch-timestamp-version`` (based on ``hatch-vcs``). Stable releases are
cut from **Git tags** (``vX.Y.Z``). Development builds use **UTC timestamped**
versions derived from the most recent tag. Version numbers come from tags, but
maintained product lines can still use long-lived ``stable/`` branches.

Versioning model
^^^^^^^^^^^^^^^^

- **Stable releases**: The version is the exact **Git tag** (for example,
  ``v0.10.0`` -> package version ``0.10.0``).
- **Development builds**: Version is computed from the latest tag **plus a
  timestamp**, for example ``0.10.1.devYYYYMMDDHHMMSS``.
- No manual editing of ``pyproject.toml`` for versions;
  ``[tool.hatch.version]`` drives everything.
- **Product compatibility** is declared separately from SemVer. The package
  version stays plain SemVer, while the package metadata declares the bundled
  ADR product release and the supported annual product lines.

Maintenance branch policy
^^^^^^^^^^^^^^^^^^^^^^^^^

- ``main`` is reserved for the next ADR product line under development.
- Long-lived maintenance branches use the ``stable/<product-line>.x`` naming
  convention.
- Stable releases are still cut from tags, but the tag should be created from
  the maintenance branch that owns that product line.
- Backport only the specific fixes you want to ship on an older supported
  line. Forward-port maintenance fixes from ``stable/<product-line>.x`` back
  to ``main`` after they are released.

Product compatibility policy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Each client major line represents one ADR compatibility epoch.
- A client line supports the current ADR annual product line and the previous
  annual product line.
- Minor and patch releases do not widen the compatibility window.
- A new client major advances the window by one annual product line and drops
  the oldest supported line.

Policy start point
""""""""""""""""""

- ``0.x`` is the legacy transition line. ``0.10.x`` remains the last legacy
  line tied to ADR ``26.1`` behavior.
- ``1.0.0`` is the first fully policy-driven line. It starts the
  product-release-aligned scheme with ADR ``27.1`` as the bundled release and
  support for the ``26.*`` and ``27.*`` annual product lines.
- Every future client major advances the supported window by exactly one ADR
  annual product line.

The client major line determines the ADR compatibility epoch:

- ``0.x`` is bundled with ADR ``26.1`` and supports the ``25.*`` and ``26.*``
  annual product lines.
- ``1.x`` is bundled with ADR ``27.1`` and supports the ``26.*`` and ``27.*``
  annual product lines.
- ``2.x`` is bundled with ADR ``28.1`` and supports the ``27.*`` and ``28.*``
  annual product lines.

ADR ``25.2`` was the final half-year release. Starting with ADR ``26.1``,
there is only one release per annual line, so ``26.*`` currently means
``26.1``, ``27.*`` means ``27.1``, and so on.

For example, under this policy:

- ``1.0.0`` is bundled with ADR ``27.1`` and supports ``26.*`` and ``27.*``.
- ``1.2.0`` and ``1.2.2`` would still support ``26.*`` and ``27.*``.
- ``2.0.0`` could bundle ADR ``28.1`` and support ``27.*`` and ``28.*``,
  dropping support for ``26.*``.

What the automation does
^^^^^^^^^^^^^^^^^^^^^^^^

- **Create Draft Release** (on tag push): builds wheels/sdist and opens a
  **draft GitHub Release** attaching artifacts. Tags ending in ``rcN`` are
  marked as prereleases.
- **Publish Release** (when the GitHub Release is **published**): uploads
  the reviewed GitHub Release artifacts to **PyPI** via Trusted Publisher,
  then builds and publishes the versioned documentation. Release-candidate
  documentation is published under its exact version while the stable
  documentation continues to point to the latest final release.
- **Failure notifications**: posts to Microsoft Teams on workflow failure.

Prerequisites
^^^^^^^^^^^^^

- Ensure ``CHANGELOG.md`` has a section for the release **dated today**. The
  helper script validates this.
- Use a fresh checkout of ``main`` or the applicable ``stable/*`` maintenance
  branch. It must track and exactly match the same branch on ``origin``.
- Working tree must be **clean**, including untracked files, and the CI-CD push
  workflow for the exact release commit must have completed successfully.
- Authenticate GitHub CLI (``gh``) for the repository so the helper can verify
  the CI run before creating the tag.
- CI secrets for publishing and docs deployment are configured in GitHub.
- The GitHub ``pypi`` environment and PyPI Trusted Publisher are configured for
  release tags matching ``v*``.

Cutting a Release
^^^^^^^^^^^^^^^^^

1. Make sure your ``CHANGELOG.md`` entry for the version is dated **today**.
   This check runs automatically from ``make tag``.
2. Create and push the release tag:

   .. code-block:: bash

      make tag

   This validates the tag syntax, changelog date, clean working tree, release
   branch and upstream commit, and successful CI-CD push run. It then creates
   and pushes the Git tag (for example, ``v0.10.0``).

   For a release candidate, pass the exact pre-release version explicitly:

   .. code-block:: bash

      make tag RELEASE_VERSION=1.0.0rc1

   An ``rcN`` tag creates a draft GitHub Release already marked as a
   prerelease. Keep that setting enabled when reviewing and publishing the
   draft.

3. Once the tag is pushed:

   - The **Create Draft Release** workflow builds the package and opens a
     **draft GitHub Release** with artifacts.
   - After reviewing and finalizing notes, publish the GitHub Release. For an
     RC, verify that the release is marked as a prerelease before publishing.

4. Publishing the release automatically triggers the **Release** workflow,
   which:

   - Downloads the artifacts attached to the reviewed GitHub Release and
     uploads those exact files to **PyPI** using Trusted Publisher.
   - Builds and publishes the versioned documentation.
   - Publishes RC documentation under its exact version, such as
     ``version/1.0.0rc1/``, without replacing the stable documentation.

Patch releases
^^^^^^^^^^^^^^

- For a patch, update the changelog, ensure the working tree is clean, then
  run ``make tag`` again. This tags the next patch version determined by
  ``hatch version`` from your last tag.
- Use the maintenance branch for the supported product line when cutting the
  tag.

Local dry-runs (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^
You can use ``act`` to exercise non-publishing parts locally. Steps that
publish or deploy are already guarded in workflows (for example, with
``if: ${{ !env.ACT }}``). Build and validation steps still run:

.. code-block:: bash

   act workflow_dispatch -W '.github/workflows/release-docs.yml' \
     -j build --bind

Manual release recovery
^^^^^^^^^^^^^^^^^^^^^^^

Manual release or documentation deployment must be dispatched from the exact
existing release tag. Do not dispatch from ``main`` and pass a separate source
reference. For example:

.. code-block:: bash

   gh workflow run create-draft-release.yml --ref v1.0.0rc1
   # OR
   gh workflow run release.yml --ref v1.0.0rc1 \
     -f deploy_versioned_docs=true
   # OR
   gh workflow run release-docs.yml --ref v1.0.0rc1 \
     -f deploy_versioned_docs=true

Use ``release.yml`` only when the PyPI upload has not completed. If PyPI
already contains the release, use the documentation-only workflow.

CI workflows (reference)
^^^^^^^^^^^^^^^^^^^^^^^^

- **.github/workflows/create-draft-release.yml**

  - Triggers on tag push ``v*`` or manual dispatch.
  - Builds artifacts and opens a **draft** GitHub Release attaching
    ``dist/*``. An ``rcN`` tag is marked as a prerelease automatically.

- **.github/workflows/release.yml**

  - Triggers on a **published** GitHub Release or manual dispatch.
  - Manual dispatches must select the exact existing release tag with
    ``--ref``.
  - Promotes the reviewed GitHub Release artifacts to **PyPI** without
    rebuilding them, then publishes versioned docs. RC docs are kept separate
    from stable docs. A manual dispatch must explicitly enable documentation
    deployment.

CLI helpers
^^^^^^^^^^^

- Print the resolved version (dev or stable):

  .. code-block:: bash

     make version

- Build locally (sdist + wheel):

  .. code-block:: bash

     make build
     make check-dist

- Clean:

  .. code-block:: bash

     make clean

Changelog guards
^^^^^^^^^^^^^^^^
Releases are blocked if today's dated entry is missing:

.. code-block:: text

   ERROR: CHANGELOG.md is not ready for release.
      Expected line: ## [0.10.0] - YYYY-MM-DD
      Tip: Check if it's still marked as '[Unreleased]' and update it to today's date.

Troubleshooting
^^^^^^^^^^^^^^^

- **"No Git tag found" during checks**: Create a tag via ``make tag`` (or
  ``git tag vX.Y.Z && git push origin vX.Y.Z``).
- **Draft asset upload failed**: Re-run ``create-draft-release.yml`` from the
  same tag. The workflow reuses the existing draft and replaces incomplete
  assets; it never creates a missing tag or modifies a published release.
- **Version mismatch**: ``hatch version`` determines the version from the last
  tag. Ensure you pushed the intended tag and your clone has all tags
  (``git fetch --tags``).

Dependencies
------------
PyDynamicReporting 1.x supports licensed ADR installations from the ``26.*``
and ``27.*`` annual product lines. This requirement applies to both connected
service mode and
``ansys.dynamicreporting.core.serverless``.

Basic usage
-----------
This code shows how to start the simplest PyDynamicReporting session:

.. code:: pycon

   >>> import ansys.dynamicreporting.core as adr
   >>> adr_service = adr.Service(ansys_installation=r"C:\\Program Files\\ANSYS Inc\\v261\\")
   >>> ret = adr_service.connect()
   >>> my_img = adr_service.create_item()
   >>> my_img.item_image = "image.png"
   >>> adr_service.visualize_report()

License and acknowledgements
----------------------------
PyDynamicReporting is licensed under the MIT license.

PyDynamicReporting makes no commercial claim over Ansys whatsoever.
This library extends the functionality of Ansys Dynamic Reporting by
adding a Python interface to Ansys Dynamic Reporting without changing
the core behavior or license of the original software. The use of
PyDynamicReporting requires a legally licensed copy of an Ansys product
that supports Ansys Dynamic Reporting.

To get a copy of Ansys, visit the `Ansys <https://www.ansys.com/>`_ website.
