Skip to content

overall doc review #210

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

overall doc review #210

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
86f3c13
overall doc review
PipKat Apr 23, 2025
66e4e59
Additional edits for cleanup and better consistency
PipKat Apr 24, 2025
ef6b8f6
Fix based on running pre-commit
PipKat Apr 24, 2025
c57c1cd
Edits based on looking at HTML artifact
PipKat Apr 24, 2025
c1ab437
Fix some lines that were too long
PipKat Apr 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,29 +34,28 @@ PyHPS Data Transfer
Overview
--------

Python client library for HPS Data Transfer Service
PyHPS Data Transfer is a Python client library for the Ansys HPC Platform Services (HPS) data transfer service.

.. contribute_start

Installation
^^^^^^^^^^^^

You can use `pip <https://pypi.org/project/pip/>`_ to install PyHPS Data Transfer.
Note: This will be available only after released. For now, please install from git
You can use `pip <https://pypi.org/project/pip/>`_ to install PyHPS Data Transfer in user mode.

.. code:: bash

pip install ansys-hps-data-transfer-client

To install the latest development version, run these commands:
To install the latest development version from the GitHub repository, run these commands:

.. code:: bash

git clone https://github.com/ansys/pyhps-data-transfer/
cd pyhps-data-transfer
pip install -e .

For more information, see `Getting Started`_.
For more information, see `Getting started`_.

Basic usage
^^^^^^^^^^^
Expand Down Expand Up @@ -87,6 +86,6 @@ To reach the project support team, email `[email protected] <mailto:pyansys


.. LINKS AND REFERENCES
.. _Getting Started: https://hps.docs.pyansys.com/version/stable/getting_started/index.html
.. _Getting started: https://hps.docs.pyansys.com/version/stable/getting_started/index.html
.. _Examples: https://hps.docs.pyansys.com/version/stable/examples.html
.. _PyHPS Data Transfer documentation: https://hps.docs.pyansys.com/version/stable/index.html
28 changes: 14 additions & 14 deletions doc/source/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,13 +60,13 @@ Installing PyHPS Data Transfer in developer mode allows you to modify and enhanc
tox

Test PyPyHPS Data Transfer
---------------------------------
--------------------------

PyHPS Data Transfer takes advantage of `tox`_. This tool allows you to automate common development
tasks (similar to ``Makefile``), but it is oriented towards Python development.

Using ``tox``
^^^^^^^^^^^^^
Use ``tox``
^^^^^^^^^^^

While ``Makefile`` has rules, ``tox`` has environments. In fact, ``tox``
creates its own virtual environment so that anything being tested is isolated
Expand All @@ -79,16 +79,16 @@ The following environment commands are provided:
- ``tox -e py-coverage``: Checks for unit testing and code coverage.
- ``tox -e doc``: Checks for documentation building.

Raw testing
^^^^^^^^^^^
Perform raw testing
^^^^^^^^^^^^^^^^^^^

If required, from the command line, you can call style commands like
`ruff`_. You can also call unit testing commands like `pytest`_.
`Ruff`_. You can also call unit testing commands like `pytest`_.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should respect the capitalization that the creators use for the name.

However, running these commands do not guarantee that your project is being tested
in an isolated environment, which is the reason why tools like ``tox`` exist.

Code style
----------
Adhere to code style
--------------------

As indicated in `Coding style <https://dev.docs.pyansys.com/coding-style/index.html>`_
in the *PyAnsys developer's guide*, PyHPS Data Transfer follows PEP8 guidelines. PyHPS Data Transfer
Expand All @@ -114,10 +114,10 @@ This way, it's not possible for you to push code that fails the style checks::
Validate GitHub Workflows................................................Passed
Add License Headers......................................................Passed

Documentation
-------------
Build documentation
-------------------

For building documentation, you can manually run these commands:
To build documentation manually, run these commands:

.. code:: bash

Expand All @@ -131,8 +131,8 @@ However, the recommended way of checking documentation integrity is to use

tox -e doc && your_browser_name .tox/doc_out/index.html

Distributing
------------
Distribute
----------

If you would like to create either source or wheel files, start by installing
the building requirements and then executing the build module:
Expand All @@ -145,7 +145,7 @@ the building requirements and then executing the build module:


.. LINKS AND REFERENCES
.. _ruff: https://docs.astral.sh/ruff/
.. _Ruff: https://docs.astral.sh/ruff/
.. _pytest: https://docs.pytest.org/en/stable/
.. _pip: https://pypi.org/project/pip/
.. _pre-commit: https://pre-commit.com/
Expand Down
8 changes: 4 additions & 4 deletions doc/source/getting_started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Getting started
===============

This section describes how to install PyHPS Data Transfer in user mode. If you are interested in contributing
to PyHPS Data Transfer.
to PyHPS Data Transfer, see :ref:`contribute` for information on installing in developer mode.

Prerequisites
-------------
Expand All @@ -18,8 +18,8 @@ You must have pip_ and Python 3.9, 3.10, 3.11, or 3.12 installed.

python --version

#. If you do not have a Python 3.x version installed, install the latest 3.x version from the
Python organization's `Downloads <https://python.org>`_ page.
#. If a Python 3.x version is not available, install the latest 3.x version from the
Python organization's `Downloads <https://www.python.org/downloads/>`_ page.

#. To see if you have ``pip`` installed, run this command:

Expand All @@ -40,7 +40,7 @@ You must have pip_ and Python 3.9, 3.10, 3.11, or 3.12 installed.
Installation
------------

To install ansys-hps-data-transfer-client in user mode, run this command:
To install PyHPS Data Transfer in user mode, run this command:

.. code:: bash

Expand Down
12 changes: 8 additions & 4 deletions doc/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,16 @@ PyHPS Data Transfer documentation |version|

Ansys HPC Platform Services (HPS) is a set of technology components designed to help you
manage the execution of simulations while making use of your full range of computing assets.
Data transfer service is a modular, plugin-based solution, which helps to solve complex data transfer problems for HPS.
PyHPS Data Transfer brings HPS data transfer client to your Python app.
Wrapping around data transfer client REST APIs, PyHPS Data Transfer allows you to:
PyHPS Data Transfer is a Python client library for the HPS data transfer service. This
modular, plugin-based solution wraps around data transfer client REST APIs to help solve
complex data transfer problems for HPS.

With PyHPS Data Transfer, you can perform these operations:

* Create and list files.
* Copy files.
* Set and view permissions.
* Delete files.


.. grid:: 1 2 2 2
Expand All @@ -20,7 +23,8 @@ Wrapping around data transfer client REST APIs, PyHPS Data Transfer allows you t
:link: getting_started/index
:link-type: doc

Learn how to install and start using PyHPS Data Transfer.
Learn how to install PyHPS Data Transfer in user mode and
quickly start using it.

.. grid-item-card:: User guide :fa:`book-open-reader`
:padding: 2 2 2 2
Expand Down
81 changes: 40 additions & 41 deletions doc/source/user_guide/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,18 @@
User guide
==========

This section walks you through the basics of how to interact with the Data transfer client service.
This section explains how to interact with the data transfer client service.

To reproduce the code samples provided in this section, you must have these
prerequisites:
To run the code samples in this section, you must have these prerequisites:

- A running Ansys HPS installation. For more information, see the
`Ansys HPC Platform Services Guide <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/prod_page.html?pn=Ansys%20HPC%20Platform%20Services&pid=HpcPlatformServices&lang=en>`_
`Ansys HPC Platform Services Deployment Guide <https://ansyshelp.ansys.com/account/secured?returnurl=/Views/Secured/prod_page.html?pn=Ansys%20HPC%20Platform%20Services&pid=HpcPlatformServices&lang=en>`_
in the Ansys Help.
- A Python shell with PyHPS Data Transfer installed. For more information, see :ref:`getting_started`.

..
This toctreemust be a top level index to get it to show up in
pydata_sphinx_theme
This toctree must be a top-level index to display in
pydata_sphinx_theme.

.. toctree::
:maxdepth: 1
Expand All @@ -28,7 +27,7 @@ prerequisites:
Connect to a data transfer service
----------------------------------

You start by connecting to the data transfer service running on the localhost with the default username and password by first requesting access token:
Before connecting to the data transfer service, which runs on the localhost with the default username and password, request the access token:

.. code-block:: python

Expand All @@ -40,8 +39,7 @@ You start by connecting to the data transfer service running on the localhost wi
token = authenticate(username="repadmin", password="repadmin", verify=False, url=auth_url)
token = token.get("access_token", None)


Using the token, connect to the data transfer service client:
Use the access token to connect to the data transfer service client:

.. code-block:: python

Expand All @@ -57,7 +55,7 @@ Using the token, connect to the data transfer service client:
api = DataTransferApi(client)
api.status(wait=True)

Once connected, you can query storages available:
Query available storages:

.. code-block:: python

Expand All @@ -67,33 +65,37 @@ Once connected, you can query storages available:
Create a directory
------------------

To create a directory:
Create a directory in a storage location:

.. code-block:: python

base_dir = "basic-example"
mkdir_op = api.mkdir([StoragePath(path=f"{base_dir}")])
api.wait_for([mkdir_op.id])
mkdir_op = api.mkdir([StoragePath(path=f"{base_dir}")])
api.wait_for([mkdir_op.id])

Copy files
----------

In the following code block, the ``local_path`` attribute is the path to the
files or directory to transfer. The ``remote_path`` attribute is the path to
the remote directory to transfer files to.

The paths used by the data transfer components follow this format:

Copying files
----------------
``[remote or keyword]:/path/to/file.txt``

In the following code block, local_path is path to the files or directory to transfer.
remote_path is path to the remote directory to transfer files to.
The paths used by the data transfer components look like
The ``[remote or keyword]`` part can be the name of a specific remote, ``any``, or be left empty. Specifying the name of a remote performs the given command only against it. Specifying ``any`` or leaving it empty runs the standard logic of the system and works through remotes in priority order.

[remote or keyword]:/path/to/file.txt
The [remote or keyword] part can be either the name of a specific remote, "any", or empty. Empty and "any" amount to the same - running the standard logic of the system, working through remotes in priority order. Specifying the name of a remote performs the given command only against it.
If an operation should be performed against a local file or directory, remove the first part, including the colon.

If an operation should be performed against a local file or directory, the first part, including the colon, should be removed.
**Examples:**

Examples:
any:mnt/test/path.txt - a file in any of the available remotes
:mnt/test/path.txt - shorthand for any:[]
s3test:some/test/path.txt - a file in storage called "s3test"
another/test/path.txt - a local path
- ``any:mnt/test/path.txt``: A file in any of the available remotes.
- ``:mnt/test/path.txt``: Shorthand for any (``[]``).
- ``s3test:some/test/path.txt``: A file named ``s3test`` in a storage location.
- ``another/test/path.txt``: A local path.

To copy files:
Copy files between storage locations:

.. code-block:: python

Expand All @@ -106,10 +108,10 @@ To copy files:
op = api.wait_for([op.id])
log.info(f"Operation {op[0].state}")

Listing files
----------------
List files
----------

To list files in a set path (base_dir in the following code block):
List files in a specified directory:

.. code-block:: python

Expand All @@ -118,11 +120,10 @@ To list files in a set path (base_dir in the following code block):
log.info(f"Operation {op[0].state}")
log.info(f"Files in {base_dir}: {op[0].result}")

Get metadata
------------

Getting metadata
----------------

To get metadata of files:
Get the metadata of a file in a specified directory:

.. code-block:: python

Expand All @@ -131,23 +132,21 @@ To get metadata of files:
md = op[0].result[f"{base_dir}/2.txt"]
log.info(f"Metadata for {base_dir}/2.txt: {md}")

Removing files
----------------
Remove files
------------

To get remove files:
Remove files in a specified directory:

.. code-block:: python

op = api.rmdir([StoragePath(path=base_dir)])
op = api.wait_for([op.id])

Stop client
----------------
-----------

To stop client:
Stop the client:

.. code-block:: python

client.stop()


Loading
Loading