rucio-clients 37.5.0__py3-none-any.whl → 37.7.0__py3-none-any.whl

rucio/cli/bin_legacy/rucio.py

@@ -26,7 +26,7 @@ import uuid
 from copy import deepcopy
 from datetime import datetime
 from logging import DEBUG
-from typing import Optional
+from typing import TYPE_CHECKING, Optional
 
 from rich.console import Console
 from rich.padding import Padding
@@ -58,6 +58,9 @@ from rucio.common.extra import import_extras
 from rucio.common.test_rucio_server import TestRucioServer
 from rucio.common.utils import Color, StoreAndDeprecateWarningAction, chunks, extract_scope, parse_did_filter_from_string, parse_did_filter_from_string_fe, setup_logger, sizefmt
 
+if TYPE_CHECKING:
+    from rucio.common.types import FileToUploadDict
+
 EXTRA_MODULES = import_extras(['argcomplete'])
 
 if EXTRA_MODULES['argcomplete']:
@@ -947,29 +950,44 @@ def upload(args, client, logger, console, spinner):
         elif len(did) == 2:
             logger.warning('Ignoring input {} because dataset DID is already set {}:{}'.format(arg, dsscope, dsname))
 
-    items = []
+    items: list[FileToUploadDict] = []
     for arg in args.args:
         if arg.count(':') > 0:
             continue
+        if args.pfn and args.impl:
+            logger.warning('Ignoring --impl option because --pfn option given')
+            args.impl = None
+
+        item: FileToUploadDict = {'path': arg, 'rse': args.rse}
+
+        if args.scope:
+            item['did_scope'] = args.scope
+        if args.name:
+            item['did_name'] = args.name
+        if dsscope:
+            item['dataset_scope'] = dsscope
+        if dsname:
+            item['dataset_name'] = dsname
+        if args.impl:
+            item['impl'] = args.impl
+        if args.protocol:
+            item['force_scheme'] = args.protocol
         if args.pfn:
-            if args.impl:
-                logger.warning('Ignoring --impl option because --pfn option given')
-                args.impl = None
-        items.append({'path': arg,
-                      'rse': args.rse,
-                      'did_scope': args.scope,
-                      'did_name': args.name,
-                      'impl': args.impl,
-                      'dataset_scope': dsscope,
-                      'dataset_name': dsname,
-                      'force_scheme': args.protocol,
-                      'pfn': args.pfn,
-                      'no_register': args.no_register,
-                      'lifetime': args.lifetime,
-                      'register_after_upload': args.register_after_upload,
-                      'transfer_timeout': args.transfer_timeout,
-                      'guid': args.guid,
-                      'recursive': args.recursive})
+            item['pfn'] = args.pfn
+        if args.no_register:
+            item['no_register'] = True
+        if args.register_after_upload:
+            item['register_after_upload'] = True
+        if args.lifetime is not None:
+            item['lifetime'] = int(args.lifetime)
+        if args.transfer_timeout is not None:
+            item['transfer_timeout'] = int(args.transfer_timeout)
+        if args.guid:
+            item['guid'] = args.guid
+        if args.recursive:
+            item['recursive'] = True
+
+        items.append(item)
 
     if len(items) < 1:
         raise InputValidationError('No files could be extracted from the given arguments')
@@ -978,6 +996,7 @@ def upload(args, client, logger, console, spinner):
         logger.error("A single GUID was specified on the command line, but there are multiple files to upload.")
         logger.error("If GUID auto-detection is not used, only one file may be uploaded at a time")
         raise InputValidationError('Invalid input argument composition')
+
     if len(items) > 1 and args.name:
         logger.error("A single LFN was specified on the command line, but there are multiple files to upload.")
         logger.error("If LFN auto-detection is not used, only one file may be uploaded at a time")
@@ -991,7 +1010,7 @@ def upload(args, client, logger, console, spinner):
     from rucio.client.uploadclient import UploadClient
     upload_client = UploadClient(client, logger=logger)
     summary_file_path = 'rucio_upload.json' if args.summary else None
-    upload_client.upload(items, summary_file_path)
+    upload_client.upload(items=items, summary_file_path=summary_file_path)
     return SUCCESS
 
 
@@ -1266,7 +1285,7 @@ def add_rule(args, client, logger, console, spinner):
     """
     %(prog)s add-rule <did> <copies> <rse-expression> [options]
 
-    Add a rule to a did.
+    Add a rule to a DID.
     """
 
     dids = []

rucio/cli/bin_legacy/rucio_admin.py

@@ -752,7 +752,7 @@ def add_scope(args, client, logger, console, spinner):
 
     """
     client.add_scope(account=args.account, scope=args.scope)
-    print('Added new scope to account: %s-%s' % (args.scope, args.account))
+    print(f'Added new scope to {args.account}: {args.scope}')
     return SUCCESS
 
 

rucio/cli/did.py

@@ -130,7 +130,7 @@ def content_history(ctx, dids):
 @click.argument("dids", nargs=-1)
 @click.pass_context
 def content_add_(ctx, to_did, from_file, dids):
-    """Attach a list [dids] of Data IDentifiers (file or collection-type) to an other Data IDentifier (collection-type)"""
+    """Attach a list [dids] of data identifiers (file or collection-type) to another data identifier (collection-type)"""
     args = Arguments({"no_pager": ctx.obj.no_pager, "dids": dids, "todid": to_did, "fromfile": from_file})
     attach(args, ctx.obj.client, ctx.obj.logger, ctx.obj.console, ctx.obj.spinner)
 
@@ -140,7 +140,7 @@ def content_add_(ctx, to_did, from_file, dids):
 @click.argument("dids", nargs=-1)
 @click.pass_context
 def content_remove(ctx, dids, from_did):
-    """Detach [dids], a list of DIDs (file or collection-type) from an other Data Identifier (collection type)"""
+    """Detach [dids], a list of DIDs (file or collection-type) from another Data Identifier (collection type)"""
     args = Arguments({"no_pager": ctx.obj.no_pager, "dids": dids, "fromdid": from_did})
     detach(args, ctx.obj.client, ctx.obj.logger, ctx.obj.console, ctx.obj.spinner)
 

rucio/cli/rse.py

@@ -55,11 +55,10 @@ def list_(ctx, rses, csv):
 
 @rse.command("show")
 @click.argument("rse-name")
-@click.option("--csv", is_flag=True, default=False, help="Output list of RSE property key and values as a csv")
 @click.pass_context
-def show(ctx, rse_name, csv):
+def show(ctx, rse_name):
     """Usage, protocols, settings, and attributes for a given RSE"""
-    info_rse(Arguments({"no_pager": ctx.obj.no_pager, "rse": rse_name, "csv": csv}), ctx.obj.client, ctx.obj.logger, ctx.obj.console, ctx.obj.spinner)
+    info_rse(Arguments({"no_pager": ctx.obj.no_pager, "rse": rse_name}), ctx.obj.client, ctx.obj.logger, ctx.obj.console, ctx.obj.spinner)
 
 
 @rse.command("add")

rucio/cli/rule.py

@@ -116,13 +116,17 @@ def move(ctx, rule_id, rses, activity, source_rses):
 @click.option("--comment", help="Comment about the replication rule")
 @click.option("--account", help="The account owning the rule")
 @click.option("--stuck", is_flag=True, default=False, help="Set state to STUCK.")
+@click.option('--suspend', is_flag=True, default=None, help='Set state to SUSPENDED.')
 @click.option("--activity", help="Activity of the rule.")
 @click.option("--cancel-requests", is_flag=True, default=False, help="Cancel requests when setting rules to stuck.")
 @click.option("--priority", help="Priority of the requests of the rule.")
 @click.option("--child-rule-id", help='Child rule id of the rule. Use "None" to remove an existing parent/child relationship.')
 @click.option("--boost-rule", is_flag=True, default=False, help="Quickens the transition of a rule from STUCK to REPLICATING.")
 @click.pass_context
-def update(ctx, rule_id, lifetime, locked, source_rses, activity, comment, account, stuck, cancel_requests, priority, child_rule_id, boost_rule):
+def update(
+    ctx, rule_id: str, lifetime: str, locked: bool, source_rses: str, activity: str, comment: str,
+    account: str, stuck: bool, suspend: bool, cancel_requests: bool, priority: str, child_rule_id: str, boost_rule: bool
+):
     """Update an existing rule"""
     args = Arguments(
         {
@@ -134,6 +138,7 @@ def update(ctx, rule_id, lifetime, locked, source_rses, activity, comment, accou
             "rule_account": account,
             "source_replica_expression": source_rses,
             "state_stuck": stuck,
+            "state_suspended": suspend,
             "cancel_requests": cancel_requests,
             "priority": priority,
             "child_rule_id": child_rule_id,
@@ -144,15 +149,14 @@ def update(ctx, rule_id, lifetime, locked, source_rses, activity, comment, accou
 
 
 @rule.command("list")
-@click.option("--did")
-@click.option("--id", "rule_id", help="List by rule id", hidden=True)  # TODO: Remove. This doesn't work and does the same thing as show
+@click.argument("did")
 @click.option("--traverse", is_flag=True, default=False, help="Traverse the did tree and search for rules affecting this did")
 @click.option("--csv", is_flag=True, default=False, help="Comma Separated Value output")
 @click.option("--file", help="Filter by file")
 @click.option("--account", help="Filter by account")
 @click.option("--subscription", help="Filter by subscription name")
 @click.pass_context
-def list_(ctx, did, rule_id, traverse, csv, file, account, subscription):
+def list_(ctx, did, traverse, csv, file, account, subscription):
     """List all rules impacting a given DID"""
-    args = Arguments({"no_pager": ctx.obj.no_pager, "did": did, "rule_id": rule_id, "traverse": traverse, "csv": csv, "file": file, "subscription": (account if account is not None else ctx.obj.client.account, subscription)})
+    args = Arguments({"no_pager": ctx.obj.no_pager, "did": did, "rule_id": None, "traverse": traverse, "csv": csv, "file": file, "subscription": (account if account is not None else ctx.obj.client.account, subscription)})
     list_rules(args, ctx.obj.client, ctx.obj.logger, ctx.obj.console, ctx.obj.spinner)

rucio/cli/subscription.py

@@ -68,6 +68,6 @@ def add_(ctx, subscription_name, did_filter, rule, comment, lifetime, account, p
 @click.pass_context
 def touch(ctx, dids):
     """Reevaluate list of DIDs against all active subscriptions"""
-    # TODO make reeval accept dids as a list
+    # TODO make reeval accept DIDs as a list
     dids = ",".join(dids)
     reevaluate_did_for_subscription(Arguments({"no_pager": ctx.obj.no_pager, "dids": dids}), ctx.obj.client, ctx.obj.logger, ctx.obj.console, ctx.obj.spinner)

rucio/client/baseclient.py

@@ -38,6 +38,7 @@ from requests.status_codes import codes
 from rucio import version
 from rucio.common import exception
 from rucio.common.config import config_get, config_get_bool, config_get_int, config_has_section
+from rucio.common.constants import DEFAULT_VO
 from rucio.common.exception import CannotAuthenticate, ClientProtocolNotFound, ClientProtocolNotSupported, ConfigNotFound, MissingClientParameter, MissingModuleException, NoAuthInformation, ServerConnectionException
 from rucio.common.extra import import_extras
 from rucio.common.utils import build_url, get_tmp_dir, my_key_generator, parse_response, setup_logger, ssh_sign
@@ -225,10 +226,10 @@ class BaseClient:
                     self.vo = config_get('client', 'vo')
                 except (NoOptionError, NoSectionError):
                     self.logger.debug('No VO found. Using default VO.')
-                    self.vo = 'def'
+                    self.vo = DEFAULT_VO
                 except ConfigNotFound:
                     self.logger.debug('No configuration found. Using default VO.')
-                    self.vo = 'def'
+                    self.vo = DEFAULT_VO
 
         self.auth_token_file_path, self.token_exp_epoch_file, self.token_file, self.token_path = self._get_auth_tokens()
         self.__authenticate()
@@ -251,7 +252,7 @@ class BaseClient:
 
         else:
             token_path = self.TOKEN_PATH_PREFIX + getpass.getuser()
-            if self.vo != 'def':
+            if self.vo != DEFAULT_VO:
                 token_path += '@%s' % self.vo
 
             token_file = token_path + '/' + self.TOKEN_PREFIX + token_filename_suffix
@@ -967,7 +968,11 @@ class BaseClient:
         if not os.path.isdir(self.token_path):
             try:
                 self.logger.debug('rucio token folder \'%s\' not found. Create it.' % self.token_path)
-                makedirs(self.token_path, 0o700)
+                try:
+                    makedirs(self.token_path, 0o700)
+                except FileExistsError:
+                    msg = f'Token directory already exists at {self.token_path} - skipping'
+                    self.logger.debug(msg)
             except Exception:
                 raise
 

rucio/client/didclient.py

@@ -55,7 +55,7 @@ class DIDClient(BaseClient):
                 like <key>.<operation>, e.g. key1 >= value1 is equivalent to {'key1.gte': value}, where <operation> belongs to one
                 of the set {'lte', 'gte', 'gt', 'lt', 'ne' or ''}. Equivalence doesn't require an operator.
             did_type :
-                The type of the did: 'all'(container, dataset or file)|'collection'(dataset or container)|'dataset'|'container'|'file'
+                The type of the DID: 'all'(container, dataset or file)|'collection'(dataset or container)|'dataset'|'container'|'file'
             long :
                 Long format option to display more information for each DID.
             recursive :
@@ -325,14 +325,14 @@ class DIDClient(BaseClient):
             ignore_duplicate: bool = False
     ) -> bool:
         """
-        Add dids to dids.
+        Add DIDs to DIDs.
 
         Parameters
         ----------
         attachments :
             The attachments.
-            An attachment contains: "scope", "name", "dids".
-            dids is: [{'scope': scope, 'name': name}, ...]
+            An attachment contains: "scope", "name", "DIDs".
+            DIDs is: [{'scope': scope, 'name': name}, ...]
         ignore_duplicate :
             If True, ignore duplicate entries.
         """
@@ -358,8 +358,8 @@ class DIDClient(BaseClient):
         ----------
         attachments :
             The attachments.
-            An attachment contains: "scope", "name", "dids".
-            dids is: [{'scope': scope, 'name': name}, ...]
+            An attachment contains: "scope", "name", "DIDs".
+            DIDs is: [{'scope': scope, 'name': name}, ...]
         ignore_duplicate :
             If True, ignore duplicate entries.
         """
@@ -377,8 +377,8 @@ class DIDClient(BaseClient):
         ----------
         attachments :
             The attachments.
-            An attachment contains: "scope", "name", "dids".
-            dids is: [{'scope': scope, 'name': name}, ...]
+            An attachment contains: "scope", "name", "DIDs".
+            DIDs is: [{'scope': scope, 'name': name}, ...]
         """
         return self.attach_dids_to_dids(attachments=attachments)
 
@@ -393,8 +393,8 @@ class DIDClient(BaseClient):
         ----------
         attachments :
             The attachments.
-            An attachment contains: "scope", "name", "dids".
-            dids is: [{'scope': scope, 'name': name}, ...]
+            An attachment contains: "scope", "name", "DIDs".
+            DIDs is: [{'scope': scope, 'name': name}, ...]
         """
         return self.attach_dids_to_dids(attachments=attachments)
 
@@ -661,7 +661,7 @@ class DIDClient(BaseClient):
         Parameters
         ----------
         dids :
-            A list of dids.
+            A list of DIDs.
         inherit :
             A boolean. If set to true, the metadata of the parent are concatenated.
         plugin :
@@ -752,7 +752,7 @@ class DIDClient(BaseClient):
         Parameters
         ----------
         dids :
-            A list of dids including metadata, i.e.
+            A list of DIDs including metadata, i.e.
             [{'scope': scope1, 'name': name1, 'meta': {key1: value1, key2: value2}}, ...].
         recursive :
             Option to propagate the metadata update to content.
@@ -902,7 +902,7 @@ class DIDClient(BaseClient):
         Returns
         -------
 
-            A did
+            A DID
         """
 
         path = '/'.join([self.DIDS_BASEURL, guid, 'guid'])
@@ -954,7 +954,7 @@ class DIDClient(BaseClient):
             name: str
     ) -> "Iterator[dict[str, Any]]":
         """
-        List parent dataset/containers of a did.
+        List parent dataset/containers of a DID.
 
         Parameters
         ----------
@@ -1016,12 +1016,12 @@ class DIDClient(BaseClient):
 
     def resurrect(self, dids: "Sequence[Mapping[str, Any]]") -> bool:
         """
-        Resurrect a list of dids.
+        Resurrect a list of DIDs.
 
         Parameters
         ----------
         dids :
-            A list of dids [{'scope': scope, 'name': name}, ...]
+            A list of DIDs [{'scope': scope, 'name': name}, ...]
         """
         path = '/'.join([self.DIDS_BASEURL, 'resurrect'])
         url = build_url(choice(self.list_hosts), path=path)

rucio/client/downloadclient.py

@@ -32,6 +32,7 @@ from rucio.client.client import Client
 from rucio.common.checksum import CHECKSUM_ALGO_DICT, GLOBALLY_SUPPORTED_CHECKSUMS, PREFERRED_CHECKSUM, adler32
 from rucio.common.client import detect_client_location
 from rucio.common.config import config_get
+from rucio.common.constants import DEFAULT_VO
 from rucio.common.didtype import DID
 from rucio.common.exception import InputValidationError, NoFilesDownloaded, NotAllFilesDownloaded, RucioException
 from rucio.common.pcache import Pcache
@@ -213,7 +214,7 @@ class DownloadClient:
         self.trace_tpl['hostname'] = self.client_location['fqdn']
         self.trace_tpl['localSite'] = self.client_location['site']
         self.trace_tpl['account'] = self.client.account
-        if self.client.vo != 'def':
+        if self.client.vo != DEFAULT_VO:
             self.trace_tpl['vo'] = self.client.vo
         self.trace_tpl['eventType'] = 'download'
         self.trace_tpl['eventVersion'] = 'api_%s' % version.RUCIO_VERSION[0]
@@ -285,7 +286,7 @@ class DownloadClient:
         -------
 
             A list of dictionaries with an entry for each file, containing the input options,
-            the did, and the clientState. clientState can be one of the following:
+            the DID, and the clientState. clientState can be one of the following:
             ALREADY_DONE, DONE, FILE_NOT_FOUND, FAIL_VALIDATE, FAILED
 
         Raises
@@ -422,7 +423,7 @@ class DownloadClient:
         -------
 
             A list of dictionaries with an entry for each file, containing the input options,
-            the did, and the clientState.
+            the DID, and the clientState.
 
         Raises
         ------
@@ -499,7 +500,7 @@ class DownloadClient:
         -------
 
             A list of dictionaries with an entry for each file, containing the input options,
-            the did, and the clientState.
+            the DID, and the clientState.
 
         Raises
         ------
@@ -1021,7 +1022,7 @@ class DownloadClient:
         -------
 
             A list of dictionaries with an entry for each file, containing the input options,
-            the did, and the clientState.
+            the DID, and the clientState.
 
 
         Raises
@@ -1173,7 +1174,7 @@ class DownloadClient:
         -------
 
             A list of dictionaries with an entry for each file, containing the input options,
-            the did, and the clientState.
+            the DID, and the clientState.
         """
         trace_custom_fields = trace_custom_fields or {}
         logger = self.logger
@@ -1322,7 +1323,7 @@ class DownloadClient:
 
     def _resolve_one_item_dids(self, item: dict[str, Any]) -> "Iterator[dict[str, Any]]":
         """
-        Resolve scopes or wildcard DIDs to lists of full did names:
+        Resolve scopes or wildcard DIDs to lists of full DID names:
 
         Parameters
         ----------
@@ -1456,10 +1457,10 @@ class DownloadClient:
             if not found_compatible_group:
                 item_groups.append([item])
 
-        # List replicas for dids
+        # List replicas for DIDs
         merged_items_with_sources = []
         for item_group in item_groups:
-            # Take configuration from the first item in the group; but dids from all items
+            # Take configuration from the first item in the group; but DIDs from all items
             item = item_group[0]
             input_dids = {DID(did): did
                           for item in item_group
@@ -1512,15 +1513,15 @@ class DownloadClient:
             logger(logging.DEBUG, 'num resolved files: %s' % len(file_items))
 
             if not nrandom or nrandom != len(file_items):
-                # If list_replicas didn't resolve any file DIDs for any input did, we pass through the input DID.
+                # If list_replicas didn't resolve any file DIDs for any input DID, we pass through the input DID.
                 # This is done to keep compatibility with later code which generates "FILE_NOT_FOUND" traces
                 # and output items.
                 # In the special case of nrandom, when serverside filtering is applied, it's "normal" for some input
-                # dids to be ignored as long as we got exactly nrandom file_items from the server.
+                # DIDs to be ignored as long as we got exactly nrandom file_items from the server.
                 for input_did in input_dids:
                     if not any([input_did == f['did'] or str(input_did) in f['parent_dids'] for f in file_items]):
                         logger(logging.ERROR, 'DID does not exist: %s' % input_did)
-                        # TODO: store did directly as DIDType object
+                        # TODO: store DID directly as DIDType object
                         file_items.append({'did': str(input_did), 'adler32': None, 'md5': None, 'sources': [], 'parent_dids': set(), 'impl': impl or None})
 
             # filtering out tape sources
@@ -1534,7 +1535,7 @@ class DownloadClient:
                         logger(logging.WARNING, 'The requested DID {} only has replicas on tape. Direct download from tape is prohibited. '
                                                 'Please request a transfer to a non-tape endpoint.'.format(file_item['did']))
 
-            # Match the file did back to the dids which were provided to list_replicas.
+            # Match the file DID back to the DIDs which were provided to list_replicas.
             # Later, this will allow to match the file back to input_items via did_to_input_items
             for file_item in file_items:
                 file_did = DID(file_item['did'])
@@ -1628,7 +1629,7 @@ class DownloadClient:
 
         all_dest_file_paths = set()
 
-        # get replicas for every file of the given dids
+        # get replicas for every file of the given DIDs
         for file_item in file_items:
             file_did = DID(file_item['did'])
             input_items = list(itertools.chain.from_iterable(did_to_input_items.get(did, []) for did in file_item['input_dids']))
@@ -1676,7 +1677,7 @@ class DownloadClient:
             file_item['dest_file_paths'] = list(dest_file_paths)
             file_item['temp_file_path'] = '%s.part' % file_item['dest_file_paths'][0]
 
-            # the file did str is not an unique key for this dict because multiple calls of list_replicas
+            # the file DID str is not a unique key for this dict because multiple calls of list_replicas
             # could result in the same DID multiple times. So we're using the id of the dictionary objects
             fiid = id(file_item)
             fiid_to_file_item[fiid] = file_item

rucio/client/exportclient.py

@@ -27,16 +27,57 @@ class ExportClient(BaseClient):
 
     def export_data(self, distance: bool = True) -> dict[str, Any]:
         """
-        Export RSE data (RSE, settings, attributes and distance).
+        Retrieve a detailed snapshot of the current RSE configuration.
+
+        The exported information includes all registered RSEs with their settings and
+        attributes. When `distance` is `True`, the RSE distance matrix is included as well.
+        The snapshot is intended for use cases such as configuration back‑ups, migrations
+        between instances, and monitoring (e.g. generating monitoring dashboards).
+
         Parameters
         ----------
-        distance :
-            To include the distance. Default is True.
+        distance
+            If *True* (default), the server also returns the inter‑RSE distance matrix in
+            the payload.
+
+            _**Note:**_ Omitting the distance information can significantly reduce the
+            response size and improve transfer times.
 
         Returns
         -------
+        dict[str, Any]
+            A nested dictionary that mirrors the server‑side JSON structure.
+            The top‑level keys are:
+
+            **`rses`**:
+                Per‑RSE settings (name, deterministic flag, QoS class, supported protocol, etc.).
+
+            **`distances`**:
+                Pairwise RSE‑to‑RSE distance values (only present when `distance=True`).
+
+        Raises
+        ------
+        RucioException
+            Raised if the HTTP status code is not *200 OK*.
+
+        Examples
+        --------
+        ??? Example
+
+            Retrieve a full export of all configured RSEs, including their attributes and
+            inter-RSE distances:
+
+            ```python
+            from rucio.client.exportclient import ExportClient
+
+            export_client = ExportClient()
 
-            A dict containing data
+            try:
+                rse_data = export_client.export_data()  # distance=True by default
+                print(f"Full RSE properties: {rse_data}")
+            except Exception as err:
+                print(f"Action failed: {err}")
+            ```
         """
         payload = {'distance': distance}
         path = '/'.join([self.EXPORT_BASEURL])

rucio/client/lockclient.py

@@ -41,9 +41,9 @@ class LockClient(BaseClient):
         Parameters
         ----------
         scope :
-            The scope of the did of the locks to list.
+            The scope of the DID of the locks to list.
         name :
-            The name of the did of the locks to list.
+            The name of the DID of the locks to list.
 
         """
 
@@ -80,7 +80,7 @@ class LockClient(BaseClient):
             list of dictionaries with lock info
         """
 
-        # convert did list to list of dictionaries
+        # convert DID list to list of dictionaries
         if not all(did.get("type", "dataset") in ("dataset", "container") for did in dids):
             raise ValueError("DID type can be either 'container' or 'dataset'")
 

rucio/client/pingclient.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 from json import loads
+from typing import Any
 
 from requests.status_codes import codes
 
@@ -21,16 +22,46 @@ from rucio.common.utils import build_url
 
 
 class PingClient(BaseClient):
-
     """Ping client class"""
 
-    def ping(self):
+    def ping(self) -> dict[str, Any]:
         """
-        Sends a ping request to the rucio server.
+        This is a light‑weight “are you alive?” call (*ping* request) to the configured Rucio.
+
+        A quick way to verify (without any required authentication):
+
+        - Network connectivity between the client and the server.
+
+        - Whether the server process is running and able to respond.
+
+        - The server’s build / version.
 
         Returns
+        -------
+        dict[str, Any]
+            A dictionary with a single key: the server version (e.g. {'version': '37.0.0'})
+
+        Raises
+        ------
+        rucio.common.exception.RucioException
+            If the HTTP status code is not *200 OK*.
+
+        Examples
         --------
-            Dictionary with server information
+        ??? Example
+
+            Basic connectivity check:
+
+            ```python
+            from rucio.client.pingclient import PingClient
+            ping_client = PingClient()
+
+            try:
+                info = ping_client.ping()
+                print(f"Connected to Rucio {info['version']}")
+            except Exception as err:
+                print(f"Ping failed: {err}")
+            ```
         """
 
         headers = None

rucio/client/replicaclient.py

@@ -416,7 +416,7 @@ class ReplicaClient(BaseClient):
 
     def list_dataset_replicas(self, scope, name, deep=False):
         """
-        List dataset replicas for a did (scope:name).
+        List dataset replicas for a DID (scope:name).
 
         Parameters
         ----------
@@ -446,7 +446,7 @@ class ReplicaClient(BaseClient):
 
     def list_dataset_replicas_bulk(self, dids):
         """
-        List dataset replicas for a did (scope:name).
+        List dataset replicas for a DID (scope:name).
 
         Parameters
         ----------