Ruleclient

Classes¶

RuleClient ¶

RuleClient(
    rucio_host=None,
    auth_host=None,
    account=None,
    ca_cert=None,
    auth_type=None,
    creds=None,
    timeout=600,
    user_agent="rucio-clients",
    vo=None,
    logger=LOG,
)

RuleClient class for working with replication rules

Methods:¶

add_replication_rule ¶

add_replication_rule(
    dids,
    copies,
    rse_expression,
    priority=3,
    lifetime=None,
    grouping="DATASET",
    notify="N",
    source_replica_expression=None,
    activity=None,
    account=None,
    meta=None,
    ignore_availability=False,
    purge_replicas=False,
    ask_approval=False,
    asynchronous=False,
    locked=False,
    delay_injection=None,
    comment=None,
    weight=None,
)

Add a replication rule. A replication rule can be used to ensure availability of a replica at different RSEs, functionally submitting a transfer request.

PARAMETER	DESCRIPTION
`dids`	The data identifier set. Format as [{"scope": scope, "name": did_name1}, {"scope": scope, "name": did_name2}, ...] TYPE: `Sequence[dict[str, str]]`
`copies`	The number of replicas. TYPE: `int`
`rse_expression`	Boolean string expression to give the list of RSEs. TYPE: `str`
`priority`	Priority of the transfers. Default is 3. TYPE: `int` DEFAULT: `3`
`lifetime`	The lifetime of the replication rules (in seconds). TYPE: `Optional[int]` DEFAULT: `None`
`grouping`	ALL - All files will be replicated to the same RSE. DATASET - All files in the same dataset will be replicated to the same RSE. NONE - Files will be completely spread over all allowed RSEs without any grouping considerations at all. Default is 'DATASET'. TYPE: `str` DEFAULT: `'DATASET'`
`notify`	Notification setting for the rule (Y [Yes], N [No], C [Close, notify when rule is closed.], P [Progress]). Default is 'N'. TYPE: `str` DEFAULT: `'N'`
`source_replica_expression`	RSE Expression for RSEs to be considered for source replicas. TYPE: `Optional[str]` DEFAULT: `None`
`activity`	Transfer Activity to be passed to FTS. TYPE: `Optional[str]` DEFAULT: `None`
`account`	The account owning the rule. TYPE: `Optional[str]` DEFAULT: `None`
`meta`	Metadata, as dictionary. TYPE: `Optional[str]` DEFAULT: `None`
`ignore_availability`	Option to ignore the availability of RSEs. Default is False. TYPE: `bool` DEFAULT: `False`
`purge_replicas`	When the rule gets deleted purge the associated replicas immediately. Default is False. TYPE: `bool` DEFAULT: `False`
`ask_approval`	Ask for approval of this replication rule. Default is False. TYPE: `bool` DEFAULT: `False`
`asynchronous`	Create rule asynchronously by judge-injector. Default is False. TYPE: `bool` DEFAULT: `False`
`locked`	If the rule is locked, it cannot be deleted. Default is False. TYPE: `bool` DEFAULT: `False`
`delay_injection`	Delay the rule injection. TYPE: `Optional[int]` DEFAULT: `None`
`comment`	Comment about the rule. TYPE: `Optional[str]` DEFAULT: `None`
`weight`	If the weighting option of the replication rule is used, the choice of RSEs takes their weight into account. TYPE: `Optional[int]` DEFAULT: `None`

RETURNS	DESCRIPTION
`Rule ID. Can be used to check the status of the rule.`

RAISES	DESCRIPTION
`InvalidRSEExpression`	The rse expression provided doesn't match any RSEs.
`DataIdentifierNotFound`	Requested DID does not exist or is otherwise specified incorrectly.
`InsufficentAccountLimit`	The account used to create the rule does not have sufficent quota on the target RSE.
`DuplicateRule`	Rule already exists with the same DID, RSE, and number of copies.
`InsufficentTargetRSEs`	There are not enough RSEs that match the RSE expression to fulfil the 'copies' requirement
`InvalidValueForKey`	Requested '0' or negative copies of a replica.

Examples:

Example

Add a rule to create a replica of the DID myscope:did at a local RSE named "LocalRSE".

from rucio.client.client import Client
client = Client()
rule_id = client.add_replication_rule([{"scope": "myscope", "name": "mydid"}], copies=1, rse_expression="LocalRSE)
print(rule_id)

See Also

rucio.client.rseclient.RSEClient.list_rses rucio.client.replicaclient.ReplicaClient.list_replicas rucio.client.ruleclient.RuleClient.delete_replication_rule rucio.client.ruleclient.RuleClient.get_replication_rule

delete_replication_rule ¶

delete_replication_rule(rule_id, purge_replicas=None)

Deletes a replication rule and all associated replica locks.

PARAMETER	DESCRIPTION
`rule_id`	The id of the rule to be deleted. TYPE: `str`
`purge_replicas`	Immediate delete the replicas TYPE: `Optional[bool]` DEFAULT: `None`

RAISES	DESCRIPTION
`RuleNotFound`	Rule ID does not exist.
`AccessDenied`	Rule does not belong, to the user associated with the client, or user has insufficent permissions.
`UnsupportedOperation`	Rule is either locked, or is a parent of child rules with "delete_parent=False" set.

RETURNS	DESCRIPTION
`True if rule is successfully deleted`

get_replication_rule ¶

get_replication_rule(rule_id)

Get a replication rule.

PARAMETER	DESCRIPTION
`rule_id`	The id of the rule to be retrieved. TYPE: `str`

RAISES	DESCRIPTION
`RuleNotFound`

RETURNS DESCRIPTION

Dictionary of rule attributes.

'id' ID of the rule 'scope' DID scope 'name' DID name 'did_type' Type of the DID (FILE, DATASET, CONTAINER) 'account' Owner of the rule 'rse_expression' RSE Expression 'copies' Number of replica copies 'grouping' How replicas are grouped (ALL, DATASET, NONE) 'lifetime' The lifetime of the replication rules (in seconds) 'locked' If the rule is locked, it cannot be deleted 'source_replica_expression' RSE Expression for RSEs to be considered for source replicas 'activity' Transfer Activity to be passed to FTS 'notify' Notification setting for the rule (Y, N, C, P) 'purge_replicas' When the rule gets deleted purge the associated replicas immediately 'ignore_availability' Option to ignore the availability of RSEs 'comment' Comment about the rule 'ask_approval' Ask for approval of this replication rule 'asynchronous' Create rule asynchronously by judge-injector 'delay_injection' Delay the rule injection 'priority' Priority of the transfers 'weight' Weighting scheme to be used 'meta' Metadata as dictionary 'state' State of the replication rule (OK, REPLICATING, STUCK, SUSPENDED, WAITING_APPROVAL, INJECT) 'error' Any error raised when creating replicas for the rule. 'created_at' Rule creation date. 'updated_at' Last modified date of rule. 'expires_at' Expiration date of the rule 'eol_at' End of life date for the replicas 'deleted_at' Date when the rule was deleted 'stuck_at' Date when the rule entered STUCK state 'child_rule_id' ID of the child rule (if this rule was replaced) 'subscription_id' ID of the subscription that created this rule 'split_container' Whether the rule was split from a container rule 'ignore_account_limit' Whether account limits were ignored when creating the rule 'notification' Notification setting for the rule (YES, NO, CLOSE, PROGRESS) 'locks_ok_cnt' Number of locks in OK state 'locks_replicating_cnt' Number of locks in REPLICATING state 'locks_stuck_cnt' Number of locks in STUCK state 'bytes' Total bytes of the DID

update_replication_rule ¶

update_replication_rule(rule_id, options)

PARAMETER	DESCRIPTION
`rule_id`	The id of the rule to be retrieved. TYPE: `str`
`options`	Options dictionary. Options dictionary can contain any of the keys used to add a rule. TYPE: `dict[str, Any]`

RAISES	DESCRIPTION
`RuleNotFound`	Rule ID was not found.
`InputValidationError`	An invalid key was passed in "options".

RETURNS	DESCRIPTION
`True if the rule was sucessfully updated.`

Examples:

Example

Update a rule with a lifetime of 0, so the rule expires.

from rucio.client.client import Client
client = Client()
rule_id = "Existing Rule ID"
client.update_replication_rule(rule_id, options={"lifetime":0})

See Also

rucio.client.ruleclient.RuleClient.add_replication_rule rucio.client.ruleclient.RuleClient.reduce_replication_rule

reduce_replication_rule ¶

reduce_replication_rule(
    rule_id, copies, exclude_expression=None
)

Downgrade the number of replica copies a rule creates. Creates a new rule and deletes the old one.

PARAMETER	DESCRIPTION
`rule_id`	The id of the rule to be reduced. TYPE: `str`
`copies`	Number of copies of the new rule. TYPE: `int`
`exclude_expression`	RSE Expression of RSEs to exclude. TYPE: `Optional[str]` DEFAULT: `None`

RAISES	DESCRIPTION
`RuleNotFound`	Rule ID does not exist
`RuleReplaceFailed`	The target rule is either not in an OK state, or requested copies is larger than current copies.
`AccessDenied`	User does not have sufficent premissions.
`InvalidRSEExpression`	The Expression ()() does not resolve to RSEs.

RETURNS	DESCRIPTION
`New rule ID.`

See Also

rucio.client.ruleclient.RuleClient.update_replication_rule

move_replication_rule ¶

move_replication_rule(rule_id, rse_expression, override)

Move a replication rule to another RSE and, once done, sets the lifetime of the original rule to 0. Creates the new rule as a child rule of the supplied rule.

PARAMETER	DESCRIPTION
`rule_id`	Rule to be moved. TYPE: `str`
`rse_expression`	RSE expression of the new rule. TYPE: `str`
`override`	Configurations to update for the new rule. TYPE: `Mapping[str, Any]`

RAISES	DESCRIPTION
`RuleNotFound`	Rule ID does not exist.
`RuleReplaceFailed`	Rule already has a child rule.
`UnsupportedOperation`	Key in override is invalid.

RETURNS	DESCRIPTION
`New rule ID.`

See Also

rucio.client.ruleclient.RuleClient.update_replication_rule rucio.client.ruleclient.RuleClient.reduce_replication_rule

approve_replication_rule ¶

approve_replication_rule(rule_id)

Admin tool used to approve pending rules. Rules with the "ask_approval" attribute can be approved this way.

An email will be sent to the user who created the rule when the rule is approved.

PARAMETER	DESCRIPTION
`rule_id`	Rule to be approved. TYPE: `str`

RAISES	DESCRIPTION
`RuleNotFound`	Rule ID does not exist
`AccessDenied`	User does not have premission to deny/approve rules.

RETURNS	DESCRIPTION
`True if rule was successfully approved.`

See Also

rucio.client.ruleclient.RuleClient.deny_replication_rule

deny_replication_rule ¶

deny_replication_rule(rule_id, reason=None)

Admin tool used to deny and delete pending rules. Rules with the "ask_approval" attribute can be denied this way.

When a rule is denied, a message is sent to the user who created the rule via the email listed on their account.

PARAMETER	DESCRIPTION
`rule_id`	Rule to be denied. TYPE: `str`
`reason`	Reason for denying the rule. TYPE: `Optional[str]` DEFAULT: `None`

RAISES	DESCRIPTION
`RuleNotFound`	Rule ID does not exist
`AccessedDenied`	User does not have premission to deny/approve rules.

RETURNS	DESCRIPTION
`True if the rule is sucessfully denied.`

See Also

rucio.client.ruleclient.RuleClient.approve_replication_rule

list_replication_rule_full_history ¶

list_replication_rule_full_history(scope, name)

List the rule history of a DID.

PARAMETER	DESCRIPTION
`scope`	The scope of the DID. TYPE: `Union[str, bytes]`
`name`	The name of the DID. TYPE: `Union[str, bytes]`

RETURNS DESCRIPTION

Iterator of rule history dictionaries with the keys:

'rule_id' ID of the rule 'account' Owner of the rule 'rse_expression' RSE Expression 'created_at' Rule creation date. 'updated_at' Last modified date of rule. 'state' State of the rule. R [Replicating], O [Ok], S [Stuck], U [Suspended], W [Waiting Approval], I [Injecting] 'locks_ok_cnt' Number of locks in OK state 'locks_replicating_cnt' Number of locks in REPLICATING state 'locks_stuck_cnt' Number of locks in STUCK state

RAISES	DESCRIPTION
`RuleNotFound`	DID not found or no rules exist for the given scope and name.

See Also

rucio.client.ruleclient.RuleClient.list_replication_rules
rucio.client.ruleclient.RuleClient.get_replication_rule

examine_replication_rule ¶

examine_replication_rule(rule_id)

Examine a replication rule for errors during transfer.

PARAMETER	DESCRIPTION
`rule_id`	The rule to examine TYPE: `str`

RETURNS	DESCRIPTION
`Dictionary with the following keys:`	'rule_error': Error message from transfer error 'transfers': List of ongoing transfer IDs

RAISES	DESCRIPTION
`RuleNotFound`

list_replica_locks ¶

list_replica_locks(rule_id)

List details of all replica locks for a rule.

PARAMETER	DESCRIPTION
`rule_id`	Rule ID TYPE: `str`

RETURNS	DESCRIPTION
`Iterator of dictionaries of replica information with the keys:`	'scope': DID Scope 'name': DID Name 'rse_id': RSE ID 'rse': RSE Name 'state': State of replica 'rule_id': Passed rule ID

RAISES	DESCRIPTION
`RuleNotFound`

See Also

rucio.client.ruleclient.RuleClient.examine_replication_rule
rucio.client.ruleclient.RuleClient.get_replication_rule

list_replication_rules ¶

list_replication_rules(filters=None)

List all replication rules which match a filter

PARAMETER	DESCRIPTION
`filters`	dictionary of attributes by which the rules should be filtered. Filters can be any of the attributes in the return dictionary. TYPE: `Optional[dict[str, Any]]` DEFAULT: `None`

RETURNS DESCRIPTION

Iterator of rule dictionaries with the keys:

'id' ID of the rule 'scope' DID scope 'name' DID name 'did_type' Type of the DID (FILE, DATASET, CONTAINER) 'account' Owner of the rule 'rse_expression' RSE Expression 'copies' Number of replica copies 'grouping' How replicas are grouped (ALL, DATASET, NONE) 'lifetime' The lifetime of the replication rules (in seconds) 'locked' If the rule is locked, it cannot be deleted 'source_replica_expression' RSE Expression for RSEs to be considered for source replicas 'activity' Transfer Activity to be passed to FTS 'notify' Notification setting for the rule (Y, N, C, P) 'purge_replicas' When the rule gets deleted purge the associated replicas immediately 'ignore_availability' Option to ignore the availability of RSEs 'comment' Comment about the rule 'ask_approval' Ask for approval of this replication rule 'asynchronous' Create rule asynchronously by judge-injector 'delay_injection' Delay the rule injection 'priority' Priority of the transfers 'weight' Weighting scheme to be used 'meta' Metadata as dictionary 'state' State of the replication rule (OK, REPLICATING, STUCK, SUSPENDED, WAITING_APPROVAL, INJECT) 'error' Any error raised when creating replicas for the rule. 'created_at' Rule creation date. 'updated_at' Last modified date of rule. 'expires_at' Expiration date of the rule 'eol_at' End of life date for the replicas 'deleted_at' Date when the rule was deleted 'stuck_at' Date when the rule entered STUCK state 'child_rule_id' ID of the child rule (if this rule was replaced) 'subscription_id' ID of the subscription that created this rule 'split_container' Whether the rule was split from a container rule 'ignore_account_limit' Whether account limits were ignored when creating the rule 'notification' Notification setting for the rule (YES, NO, CLOSE, PROGRESS) 'locks_ok_cnt' Number of locks in OK state 'locks_replicating_cnt' Number of locks in REPLICATING state 'locks_stuck_cnt' Number of locks in STUCK state 'bytes' Total bytes of the DID

RAISES	DESCRIPTION
`RucioException`	An invalid key is passed as a filter.

See Also

rucio.client.ruleclient.RuleClient.add_replication_rule
rucio.client.ruleclient.RuleClient.get_replication_rule

Ruleclient

Classes¶

RuleClient ¶

Methods:¶

add_replication_rule ¶

delete_replication_rule ¶

get_replication_rule ¶

update_replication_rule ¶

reduce_replication_rule ¶

move_replication_rule ¶

approve_replication_rule ¶

deny_replication_rule ¶

list_replication_rule_full_history ¶

examine_replication_rule ¶

list_replica_locks ¶

list_replication_rules ¶

Functions:¶