



PDM 1.0.0 documentation

Welcome to PDM’s documentation![¶](#welcome-to-pdm-s-documentation "Permalink to this headline")

================================================================================================

pdm package[¶](#module-pdm "Permalink to this headline")

--------------------------------------------------------

### Subpackages[¶](#subpackages "Permalink to this headline")

#### pdm.CLI package[¶](#module-pdm.CLI "Permalink to this headline")

##### Submodules[¶](#submodules "Permalink to this headline")

##### pdm.CLI.filemode module[¶](#pdm-cli-filemode-module "Permalink to this headline")

Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The Netherlands.

PSF LICENSE AGREEMENT FOR PYTHON 3.6.5

1. This LICENSE AGREEMENT is between the Python Software Foundation (“PSF”), and

the Individual or Organization (“Licensee”) accessing and otherwise using Python

3.6.5 software in source or binary form and its associated documentation.

2. Subject to the terms and conditions of this License Agreement, PSF hereby

grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce,

analyze, test, perform and/or display publicly, prepare derivative works,

distribute, and otherwise use Python 3.6.5 alone or in any derivative

version, provided, however, that PSF’s License Agreement and PSF’s notice of

copyright, i.e., “Copyright 2001-2018 Python Software Foundation; All Rights

Reserved” are retained in Python 3.6.5 alone or in any derivative version

prepared by Licensee.

3. In the event Licensee prepares a derivative work that is based on or

incorporates Python 3.6.5 or any part thereof, and wants to make the

derivative work available to others as provided herein, then Licensee hereby

agrees to include in any such work a brief summary of the changes made to Python

3.6.5.

4. PSF is making Python 3.6.5 available to Licensee on an “AS IS” basis.

PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF

EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR

WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE

USE OF PYTHON 3.6.5 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.

5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON 3.6.5

FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF

MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 3.6.5, OR ANY DERIVATIVE

THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.

6. This License Agreement will automatically terminate upon a material breach of

its terms and conditions.

7. Nothing in this License Agreement shall be deemed to create any relationship

of agency, partnership, or joint venture between PSF and Licensee. This License

Agreement does not grant permission to use PSF trademarks or trade name in a

trademark sense to endorse or promote products or services of Licensee, or any

third party.

8. By copying, installing or otherwise using Python 3.6.5, Licensee agrees

to be bound by the terms and conditions of this License Agreement.

`pdm.CLI.filemode.``filemode`(*mode*)[[source]](_modules/pdm/CLI/filemode.html#filemode)[¶](#pdm.CLI.filemode.filemode "Permalink to this definition")

Convert a file’s mode to a string of the form ‘-rwxrwxrwx’.

##### pdm.CLI.pdmcli module[¶](#module-pdm.CLI.pdmcli "Permalink to this headline")

PDM Command Line Interface.

`pdm.CLI.pdmcli.``main`(*opt\_conf\_file=None*)[[source]](_modules/pdm/CLI/pdmcli.html#main)[¶](#pdm.CLI.pdmcli.main "Permalink to this definition")

Main CLI function. Reads configuration and adds subparsers.

The order configuration file is searched for:

* *-c/–config* command line switch

* *PDM\_CLIENT\_CONF* environment variable

* *~/.pdm/client.conf* or */etc/pdm/client.conf*

* a file pointed to by the argument passed in.

| Parameters: | **opt\_conf\_file** – an optional config file location |

| Returns: | None |

##### pdm.CLI.user\_subcommand module[¶](#module-pdm.CLI.user_subcommand "Permalink to this headline")

Define *pdm* sub-commands and action functions for them:

Example usage: *pdm register -e fred@flintstones.com -n Fred -s Flintstone*

*class* `pdm.CLI.user_subcommand.``UserCommand`(*subparsers*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand)[¶](#pdm.CLI.user_subcommand.UserCommand "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Define user sub-commands and assign actions to them. Use *pdm -h* to see all subcommands.

To see accepted sub-command parameters use *pdm subcmd -h* where *subcmd* is a sub-command

name i.e. *pdm register -h*

`add_site`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.add_site)[¶](#pdm.CLI.user_subcommand.UserCommand.add_site "Permalink to this definition")

Add a site to the database.

| Parameters: | **args** – parser arguments |

| Returns: | None |

`copy`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.copy)[¶](#pdm.CLI.user_subcommand.UserCommand.copy "Permalink to this definition")

Copy files between sites. Not executed if no valid token or not logged in

to either of the sites.

| Parameters: | **args** – parser argumens, in parcicular source and destination site paths. |

| Returns: | copy response or *None* if site paths were malformed.

see: [`pdm.userservicedesk.TransferClientFacade.TransferClientFacade.copy()`](index.html#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.copy "pdm.userservicedesk.TransferClientFacade.TransferClientFacade.copy") |

`del_site`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.del_site)[¶](#pdm.CLI.user_subcommand.UserCommand.del_site "Permalink to this definition")

Delete a site.

| Parameters: | **args** – parser arguments. |

| Returns: | None |

`get_session`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.get_session)[¶](#pdm.CLI.user_subcommand.UserCommand.get_session "Permalink to this definition")

Get and prints formatted user session information

from the `pdm.site.SiteClient.SiteClient` for a given site.

| Parameters: | **args** – parser arguments, in particular the site name. |

| Returns: | None |

`get_site`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.get_site)[¶](#pdm.CLI.user_subcommand.UserCommand.get_site "Permalink to this definition")

Get and pretty-print site information by calling `pdm.site.SiteClient.SiteClient.get\_site()` for a given site.

| Parameters: | **args** – parser arguments, in particular site name. |

| Returns: | None |

`jobs`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.jobs)[¶](#pdm.CLI.user_subcommand.UserCommand.jobs "Permalink to this definition")

Get user jobs’ info. See [`pdm.userservicedesk.TransferClient.TransferClient.jobs()`](index.html#pdm.userservicedesk.TransferClient.TransferClient.jobs "pdm.userservicedesk.TransferClient.TransferClient.jobs")

| Parameters: | **args** – parser arguments. |

| Returns: | None |

`list`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.list)[¶](#pdm.CLI.user_subcommand.UserCommand.list "Permalink to this definition")

List files at remote site.

| Parameters: | **args** – parser arguments. |

| Returns: | None |

`log`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.log)[¶](#pdm.CLI.user_subcommand.UserCommand.log "Permalink to this definition")

Get job log of a complete finished job (get *log* element of the job output).

Use -v to get complete job info.

| Parameters: | **args** – parser arguments, in particualr the job *id*. |

| Returns: | None

see: [`pdm.userservicedesk.TransferClient.TransferClient.output()`](index.html#pdm.userservicedesk.TransferClient.TransferClient.output "pdm.userservicedesk.TransferClient.TransferClient.output") |

`login`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.login)[¶](#pdm.CLI.user_subcommand.UserCommand.login "Permalink to this definition")

User login function. Stores a token obtained from the server in a file.

`logoff`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.logoff)[¶](#pdm.CLI.user_subcommand.UserCommand.logoff "Permalink to this definition")

User logoff. Just delete a token if present.

| Parameters: | **args** – parser arguments. |

| Returns: | None |

`mkdir`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.mkdir)[¶](#pdm.CLI.user_subcommand.UserCommand.mkdir "Permalink to this definition")

Create a new directory at a site.

| Parameters: | **args** – site - the new directory in a form site:path |

| Returns: | None

see: [`pdm.userservicedesk.TransferClientFacade.TransferClientFacade.mkdir()`](index.html#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.mkdir "pdm.userservicedesk.TransferClientFacade.TransferClientFacade.mkdir") |

`not_implemented`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.not_implemented)[¶](#pdm.CLI.user_subcommand.UserCommand.not_implemented "Permalink to this definition")

Not Implemented yet placeholder.

| Parameters: | **args** –  |

| Returns: |  |

`passwd`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.passwd)[¶](#pdm.CLI.user_subcommand.UserCommand.passwd "Permalink to this definition")

Change user password.

`register`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.register)[¶](#pdm.CLI.user_subcommand.UserCommand.register "Permalink to this definition")

User registration function. It will ask for an email address, name, surname

and a password.

| Parameters: | **args** – parser arguments when called by the master command (pdm) |

| Returns: | None |

`remove`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.remove)[¶](#pdm.CLI.user_subcommand.UserCommand.remove "Permalink to this definition")

Remove files at remote site.

| Parameters: | **args** – parser arguments, in particular *sitename:patname* to remove. |

| Returns: | None

see: [`pdm.userservicedesk.TransferClientFacade.TransferClientFacade.remove()`](index.html#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.remove "pdm.userservicedesk.TransferClientFacade.TransferClientFacade.remove") |

`rename`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.rename)[¶](#pdm.CLI.user_subcommand.UserCommand.rename "Permalink to this definition")

Rename a file at a site. It’s like a copy, but with the source and destination

site being the same.

| Parameters: | **args** – old name: site:path, new name: :path. |

| Returns: | None

see: [`pdm.userservicedesk.TransferClientFacade.TransferClientFacade.rename()`](index.html#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.rename "pdm.userservicedesk.TransferClientFacade.TransferClientFacade.rename") |

`resend_email`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.resend_email)[¶](#pdm.CLI.user_subcommand.UserCommand.resend_email "Permalink to this definition")

Resend verification email.

| Parameters: | **args** – parser arguments (email address) |

| Returns: | None |

`site_login`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.site_login)[¶](#pdm.CLI.user_subcommand.UserCommand.site_login "Permalink to this definition")

User site logon.

| Parameters: | **args** – parser arguments |

| Returns: | None |

`site_logoff`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.site_logoff)[¶](#pdm.CLI.user_subcommand.UserCommand.site_logoff "Permalink to this definition")

User site logoff.

| Parameters: | **args** – parser arguments. |

| Returns: | None |

`sitelist`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.sitelist)[¶](#pdm.CLI.user_subcommand.UserCommand.sitelist "Permalink to this definition")

Print list of available sites.

| Parameters: | **args** – carry a user token |

| Returns: | None |

`status`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.status)[¶](#pdm.CLI.user_subcommand.UserCommand.status "Permalink to this definition")

Get and print status of a job (task).

| Parameters: | **args** –  |

| Returns: | None

see: [`pdm.userservicedesk.TransferClient.TransferClient.status()`](index.html#pdm.userservicedesk.TransferClient.TransferClient.status "pdm.userservicedesk.TransferClient.TransferClient.status") |

`unregister`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.unregister)[¶](#pdm.CLI.user_subcommand.UserCommand.unregister "Permalink to this definition")

Deletes a user from the pdm user database. A user can only delete himself.

Result of the operation is printed to the console.

| Parameters: | **args** – parser arguments. |

| Returns: | None |

`verify`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.verify)[¶](#pdm.CLI.user_subcommand.UserCommand.verify "Permalink to this definition")

Verify user’s email address.

| Parameters: | **args** – parser arguments |

| Returns: | None |

`whoami`(*args*)[[source]](_modules/pdm/CLI/user_subcommand.html#UserCommand.whoami)[¶](#pdm.CLI.user_subcommand.UserCommand.whoami "Permalink to this definition")

get users own data.

#### pdm.userservicedesk package[¶](#module-pdm.userservicedesk "Permalink to this headline")

##### Submodules[¶](#submodules "Permalink to this headline")

##### pdm.userservicedesk.HRClient module[¶](#module-pdm.userservicedesk.HRClient "Permalink to this headline")

RESTful client API for the HRService service

*class* `pdm.userservicedesk.HRClient.``HRClient`[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient)[¶](#pdm.userservicedesk.HRClient.HRClient "Permalink to this definition")

Bases: `pdm.framework.RESTClient.RESTClient`

RESTful user management client API

`add_user`(*userdict*)[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.add_user)[¶](#pdm.userservicedesk.HRClient.HRClient.add_user "Permalink to this definition")

Add a new user.

| Parameters: | **userdict** – user input data dictionary. |

The required fields (strings) are:

* key: ‘email’ value: a valid user email which server as a username

* key: ‘name’ value: user given name e.g. ‘John’

* key: ‘surname’ value: user surname e.g. ‘Smith’

* key: ‘password’ value: password

| Returns: | Returns a dict with user data for convenience. |

`change_password`(*password*, *newpassword*)[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.change_password)[¶](#pdm.userservicedesk.HRClient.HRClient.change_password "Permalink to this definition")

Request user password change.

| Parameters: | * **password** – original password

* **newpassword** – new password

 |

| Returns: | a dictionary with user data |

`del_user`()[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.del_user)[¶](#pdm.userservicedesk.HRClient.HRClient.del_user "Permalink to this definition")

Deletes a user.

| Returns: | None |

`get_user`()[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.get_user)[¶](#pdm.userservicedesk.HRClient.HRClient.get_user "Permalink to this definition")

Get user’s own data

:return: a dictionary containing user data

`hello`()[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.hello)[¶](#pdm.userservicedesk.HRClient.HRClient.hello "Permalink to this definition")

Call the hello function on the server and return the result.

`login`(*username*, *password*)[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.login)[¶](#pdm.userservicedesk.HRClient.HRClient.login "Permalink to this definition")

User login procedure. Gets a token issued by a service.

The client has to pass the token received to the set\_token()

operation in order to be able to use operations which require

a token (e.g. get\_user() ).

| Parameters: | * **username** – email address

* **password** – password

 |

| Returns: | user token |

`resend_email`(*userdict*)[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.resend_email)[¶](#pdm.userservicedesk.HRClient.HRClient.resend_email "Permalink to this definition")

(Re)send a verification email containing the mail token.

:param userdict: a dict containg a email address to send an email to as {‘email’: <address>}

:return:

`verify_user`(*tokendict*)[[source]](_modules/pdm/userservicedesk/HRClient.html#HRClient.verify_user)[¶](#pdm.userservicedesk.HRClient.HRClient.verify_user "Permalink to this definition")

Verify user’s email address.

| Parameters: | **tokendict** – {‘mailtoken’ : token}. token is a base64 encoded string received by email. |

| Returns: |  |

##### pdm.userservicedesk.HRService module[¶](#module-pdm.userservicedesk.HRService "Permalink to this headline")

User Interface Service

*class* `pdm.userservicedesk.HRService.``HRService`[[source]](_modules/pdm/userservicedesk/HRService.html#HRService)[¶](#pdm.userservicedesk.HRService.HRService "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

User Interface RESTful Web Service class.

*static* `add_user`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.add_user)[¶](#pdm.userservicedesk.HRService.HRService.add_user "Permalink to this definition")

Add a new user.

| Returns: | json document with added user data. An HTTPException with a

403 status code is thrown when the user already exists. User

email address and a password are obligatory (404 is emitted

otherwise). |

*static* `change_password`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.change_password)[¶](#pdm.userservicedesk.HRService.HRService.change_password "Permalink to this definition")

Method to change user password. Requite old password, new password and a valid token.

| Returns: | response object containing user name, surname and date modified |

*static* `check_passwd`(*passwd*)[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.check_passwd)[¶](#pdm.userservicedesk.HRService.HRService.check_passwd "Permalink to this definition")

Very basic password check.

| Parameters: | **passwd** – password to be checked. |

| Returns: | True of False |

*static* `check_token`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.check_token)[¶](#pdm.userservicedesk.HRService.HRService.check_token "Permalink to this definition")

Token validity helper. Check token integrity and expiry date. Emit 403 if the check fails.

| Returns: | user id from the token. |

*static* `compose_and_send`(*to\_address*, *mail\_token*, *local\_exp*)[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.compose_and_send)[¶](#pdm.userservicedesk.HRService.HRService.compose_and_send "Permalink to this definition")

Compose the email. Initialise the SMTP server, login and send the email.

Raises a RuntimeError if any of the email preparation and sending steps fail.

| Parameters: | * **to\_address** – mail recipient address.

* **mail\_token** – a url with a token included in the email body.

* **local\_exp** – token expiry datetime in the server’s local timezone.

 |

| Returns: | None |

`db_model` *= [<class 'pdm.userservicedesk.models.UserModel'>]*[¶](#pdm.userservicedesk.HRService.HRService.db_model "Permalink to this definition")

*static* `delete_user`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.delete_user)[¶](#pdm.userservicedesk.HRService.HRService.delete_user "Permalink to this definition")

Delete a user. The user can only delete himself.

| Returns: | response object with code 200 if successful, 404 if the user does not exist |

*static* `email_user`(*to\_address*)[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.email_user)[¶](#pdm.userservicedesk.HRService.HRService.email_user "Permalink to this definition")

Send an email to a user identified by to\_address. Raises a RuntimeError if

unsuccessful.

| Parameters: | **to\_address** – user email |

| Returns: | None |

`exportables` *= [('/users/api/v1.0', ['GET'], None)]*[¶](#pdm.userservicedesk.HRService.HRService.exportables "Permalink to this definition")

*static* `get_token`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.get_token)[¶](#pdm.userservicedesk.HRService.HRService.get_token "Permalink to this definition")

User login procedure.

| Returns: | token |

*static* `get_token_userid`(*token*)[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.get_token_userid)[¶](#pdm.userservicedesk.HRService.HRService.get_token_userid "Permalink to this definition")

Get the value of the ‘key’ part of the token to be used to contact the CS

The token holds internally:

id: user id

expiry: expiry info (to be decided)

key: hashed key (from pdm.utils.hashing.hash\_pass()).

| Parameters: | **token** – encrypted token |

| Returns: | the value of the ‘key’ field of the token dictionary |

*static* `get_user`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.get_user)[¶](#pdm.userservicedesk.HRService.HRService.get_user "Permalink to this definition")

Get user own self based on user\_id from the token passed in.

| Returns: | json response with user data or 404 if the user does not exist |

*static* `hello`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.hello)[¶](#pdm.userservicedesk.HRService.HRService.hello "Permalink to this definition")

Ping-like method.

| Returns: | nice greeting ;-) |

`is_exported` *= True*[¶](#pdm.userservicedesk.HRService.HRService.is_exported "Permalink to this definition")

*static* `load_userconfig`(*config*)[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.load_userconfig)[¶](#pdm.userservicedesk.HRService.HRService.load_userconfig "Permalink to this definition")

Configure the HRService application.

Gets the key needed to contact the Credential Service

*static* `resend_email`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.resend_email)[¶](#pdm.userservicedesk.HRService.HRService.resend_email "Permalink to this definition")

Re-send a verification email for registered but not verified users.

:return:

*static* `update_user_status`(*username*, *status*, *flag=False*)[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.update_user_status)[¶](#pdm.userservicedesk.HRService.HRService.update_user_status "Permalink to this definition")

Update user status in the db.

:param username: user email address

:param status: new status

:param flag: if True update to the same status is allowed.

:return: None

*static* `verify_user`()[[source]](_modules/pdm/userservicedesk/HRService.html#HRService.verify_user)[¶](#pdm.userservicedesk.HRService.HRService.verify_user "Permalink to this definition")

Verify users’ email address. Data posted is a token which has to ve verified and unpacked.

The email address contained in the token is compared with the email stored in the DB.

User state is changed to 1 (verified) if successful.

:return:

*class* `pdm.userservicedesk.HRService.``HRServiceUserState`[[source]](_modules/pdm/userservicedesk/HRService.html#HRServiceUserState)[¶](#pdm.userservicedesk.HRService.HRServiceUserState "Permalink to this definition")

Bases: [`enum.IntEnum`](https://docs.python.org/3/library/enum.html#enum.IntEnum "(in Python v3.8)")

User State enumeration.

`DISABLED` *= -1*[¶](#pdm.userservicedesk.HRService.HRServiceUserState.DISABLED "Permalink to this definition")

`REGISTERED` *= 0*[¶](#pdm.userservicedesk.HRService.HRServiceUserState.REGISTERED "Permalink to this definition")

`VERIFIED` *= 1*[¶](#pdm.userservicedesk.HRService.HRServiceUserState.VERIFIED "Permalink to this definition")

##### pdm.userservicedesk.HRUtils module[¶](#module-pdm.userservicedesk.HRUtils "Permalink to this headline")

User Interface Service Utilities

*class* `pdm.userservicedesk.HRUtils.``HRUtils`[[source]](_modules/pdm/userservicedesk/HRUtils.html#HRUtils)[¶](#pdm.userservicedesk.HRUtils.HRUtils "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Utility class for the HRService. Currently it contains only client side insecure

token handling methods

*static* `get_token_expiry_insecure`(*token*)[[source]](_modules/pdm/userservicedesk/HRUtils.html#HRUtils.get_token_expiry_insecure)[¶](#pdm.userservicedesk.HRUtils.HRUtils.get_token_expiry_insecure "Permalink to this definition")

Get token expiry date in ISO format, Insecure - token integrity not checked.

| Parameters: | **token** – token in |

| Returns: | ISO of the unpacked token |

*static* `get_token_username_insecure`(*token*)[[source]](_modules/pdm/userservicedesk/HRUtils.html#HRUtils.get_token_username_insecure)[¶](#pdm.userservicedesk.HRUtils.HRUtils.get_token_username_insecure "Permalink to this definition")

Get username from a token.

| Parameters: | **token** –  |

| Returns: |  |

*static* `is_date_passed`(*expiry\_iso*)[[source]](_modules/pdm/userservicedesk/HRUtils.html#HRUtils.is_date_passed)[¶](#pdm.userservicedesk.HRUtils.HRUtils.is_date_passed "Permalink to this definition")

Check if date is in the past. None date is treated like one in the past.

:param expiry\_iso: data in ISO format

:return: True if date is in the past, or if it is None.

*static* `is_token_expired_insecure`(*token*)[[source]](_modules/pdm/userservicedesk/HRUtils.html#HRUtils.is_token_expired_insecure)[¶](#pdm.userservicedesk.HRUtils.HRUtils.is_token_expired_insecure "Permalink to this definition")

Check whether token is expired. This is an insecure call - it does not verify

token’s integrity.

| Parameters: | **token** – token in |

| Returns: | True if expired or no expiry information; False otherwise. |

*static* `utc_to_local`(*dt\_obj*)[[source]](_modules/pdm/userservicedesk/HRUtils.html#HRUtils.utc_to_local)[¶](#pdm.userservicedesk.HRUtils.HRUtils.utc_to_local "Permalink to this definition")

##### pdm.userservicedesk.TransferClient module[¶](#module-pdm.userservicedesk.TransferClient "Permalink to this headline")

Client API for the file transfer management

*class* `pdm.userservicedesk.TransferClient.``TransferClient`(*user\_token*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient)[¶](#pdm.userservicedesk.TransferClient.TransferClient "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Transfer management client API. To list, copy and remove files from remote site.

`copy`(*src\_site*, *src\_filepath*, *dst\_site*, *dst\_filepath*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.copy)[¶](#pdm.userservicedesk.TransferClient.TransferClient.copy "Permalink to this definition")

Copy files between sites.

| Parameters: | * **src\_site** – source site

* **src\_filepath** – source site path

* **dst\_site** – destination site

* **dst\_filepath** – destination site path

* **kwargs** –

	+ max\_tries: maximum number of attempts

	+ priority: priority

	+ protocol: protocol used, see: [`pdm.workqueue.WorkqueueClient.WorkqueueClient.copy()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.copy "pdm.workqueue.WorkqueueClient.WorkqueueClient.copy")

 |

| Returns: | forward response from [`pdm.workqueue.WorkqueueClient.WorkqueueClient.copy()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.copy "pdm.workqueue.WorkqueueClient.WorkqueueClient.copy")

or *None* if either of the sites exists. |

`elements`(*job\_id*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.elements)[¶](#pdm.userservicedesk.TransferClient.TransferClient.elements "Permalink to this definition")

Get job elements information.

| Parameters: | **job\_id** – job id |

| Returns: | forwarded response from [`WorkqueueClient.jobs()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.jobs "pdm.workqueue.WorkqueueClient.WorkqueueClient.jobs"). |

`jobs`()[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.jobs)[¶](#pdm.userservicedesk.TransferClient.TransferClient.jobs "Permalink to this definition")

Get user jobs’ info.

| Returns: | forwarded response from [`WorkqueueClient.jobs()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.jobs "pdm.workqueue.WorkqueueClient.WorkqueueClient.jobs"). |

`list`(*src\_site*, *src\_filepath*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.list)[¶](#pdm.userservicedesk.TransferClient.TransferClient.list "Permalink to this definition")

List a given path. As for all client calls it need a user token set in a request beforehand.

| Parameters: | * **src\_site** (*string*) – The name of the site containing the path to be listed.

* **src\_filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The path to list.

* **kwargs** – keyword arguments containing: protocol, max\_tries and priority

 |

| Returns: | The Python dictionary representing the list of files. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`list_sites`()[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.list_sites)[¶](#pdm.userservicedesk.TransferClient.TransferClient.list_sites "Permalink to this definition")

Get list of sites.

| Returns: | list of dictionaries with all keys but ‘site\_id’. |

`mkdir`(*site*, *dirpath*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.mkdir)[¶](#pdm.userservicedesk.TransferClient.TransferClient.mkdir "Permalink to this definition")

Create a new directory at a site.

| Parameters: | * **site** – site name

* **dirpath** – directory path

* **kwargs** –

	+ max\_tries: maximum number of attempts

	+ priority: priority

	+ protocol: protocol used, see: [`pdm.workqueue.WorkqueueClient.WorkqueueClient.copy()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.copy "pdm.workqueue.WorkqueueClient.WorkqueueClient.copy")

 |

| Returns: | forward response from [`pdm.workqueue.WorkqueueClient.WorkqueueClient.mkdir()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.mkdir "pdm.workqueue.WorkqueueClient.WorkqueueClient.mkdir")

or *None* if the site does not exist. |

`output`(*job\_id*, *element\_id=None*, *attempt=None*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.output)[¶](#pdm.userservicedesk.TransferClient.TransferClient.output "Permalink to this definition")

Get job output.

| Parameters: | **job\_id** – job id |

| Returns: | output as specified by workqueue client |

`remove`(*src\_site*, *src\_filepath*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.remove)[¶](#pdm.userservicedesk.TransferClient.TransferClient.remove "Permalink to this definition")

Remove files from a given site.

| Parameters: | * **src\_site** – the site to contact

* **src\_filepath** – the path to be removed

* **kwargs** –

	+ max\_tries: maximum number of attempts

	+ priority: priority

	+ protocol: protocol used

 |

| Returns: | forward response from [`pdm.workqueue.WorkqueueClient.WorkqueueClient.remove()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.remove "pdm.workqueue.WorkqueueClient.WorkqueueClient.remove")

or *None* if the source site does not exist. |

`rename`(*site*, *oldname*, *newname*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.rename)[¶](#pdm.userservicedesk.TransferClient.TransferClient.rename "Permalink to this definition")

Rename a file or directory within site.

| Parameters: | * **site** – site name

* **oldname** – old file name

* **newname** – new file name

* **kwargs** –

	+ max\_tries: maximum number of attempts

	+ priority: priority

	+ protocol: protocol used

 |

| Returns: | forward response from [`pdm.workqueue.WorkqueueClient.WorkqueueClient.rename()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.rename "pdm.workqueue.WorkqueueClient.WorkqueueClient.rename")

or *None* if the site does not exist. |

`status`(*job\_id*, *element\_id=None*)[[source]](_modules/pdm/userservicedesk/TransferClient.html#TransferClient.status)[¶](#pdm.userservicedesk.TransferClient.TransferClient.status "Permalink to this definition")

Return status of a job.

| Parameters: | **job\_id** – job id to get the status of. |

| Returns: | forward response from [`pdm.workqueue.WorkqueueClient.WorkqueueClient.status()`](index.html#pdm.workqueue.WorkqueueClient.WorkqueueClient.status "pdm.workqueue.WorkqueueClient.WorkqueueClient.status"). |

##### pdm.userservicedesk.TransferClientFacade module[¶](#module-pdm.userservicedesk.TransferClientFacade "Permalink to this headline")

The Facade for the TransferClient. Uses site as an argument to most

of the methods (rather them its parts)

*class* `pdm.userservicedesk.TransferClientFacade.``TransferClientFacade`(*token*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade "Permalink to this definition")

Bases: [`pdm.userservicedesk.TransferClient.TransferClient`](#pdm.userservicedesk.TransferClient.TransferClient "pdm.userservicedesk.TransferClient.TransferClient")

Transfer client facade. Methods take *sitename:path* as parameter(s)

rather the its parts.

`copy`(*src\_site*, *dst\_site*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade.copy)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.copy "Permalink to this definition")

Copy files or directories from one site to another.

| Parameters: | * **src\_site** – source site

* **dst\_site** – destination site

* **kwargs** – additional arguments (like max\_tries or priority)

 |

| Returns: | copy result message |

`list`(*site*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade.list)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.list "Permalink to this definition")

List the resource specified by site.

| Parameters: | * **site** – site to list

* **kwargs** – additional arguments (like max\_tries or priority)

 |

| Returns: | the resource listing |

`mkdir`(*sitepath*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade.mkdir)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.mkdir "Permalink to this definition")

Create a new directory at the site.

| Parameters: | **site\_path** – string of a form sitename:directory\_path\_to\_create |

| Returns: | mkdir result message, or *None* if malformed site path |

`remove`(*src\_site*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade.remove)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.remove "Permalink to this definition")

Remove the resources (file or directory).

| Parameters: | * **src\_site** – site to remove from

* **kwargs** – additional arguments (like max\_tries or priority)

 |

| Returns: | remove result message |

`rename`(*site\_path*, *newname*, *\*\*kwargs*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade.rename)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.rename "Permalink to this definition")

Rename a file.

| Parameters: | **site\_path** – string of a form sitename:file\_path\_to\_rename |

:param newname new file name (w/o the site prefix)

:return: rename result message, or None if malformed site path

*static* `split_site_path`(*path*)[[source]](_modules/pdm/userservicedesk/TransferClientFacade.html#TransferClientFacade.split_site_path)[¶](#pdm.userservicedesk.TransferClientFacade.TransferClientFacade.split_site_path "Permalink to this definition")

Split a site string at the first colon. Return a tuple containing a *(site, path)* or

*(None, None)* if the *path* is malformed.

##### pdm.userservicedesk.models module[¶](#module-pdm.userservicedesk.models "Permalink to this headline")

Database model for User service.

*class* `pdm.userservicedesk.models.``UserModel`(*db\_base*)[[source]](_modules/pdm/userservicedesk/models.html#UserModel)[¶](#pdm.userservicedesk.models.UserModel "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

User service tables.

#### pdm.utils package[¶](#module-pdm.utils "Permalink to this headline")

A collection of misc. utilities for PDM.

##### Submodules[¶](#submodules "Permalink to this headline")

##### pdm.utils.X509 module[¶](#module-pdm.utils.X509 "Permalink to this headline")

X509 CA: Modules for issuing certificates.

*class* `pdm.utils.X509.``X509Utils`[[source]](_modules/pdm/utils/X509.html#X509Utils)[¶](#pdm.utils.X509.X509Utils "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

A series of helper functions for X509 objects.

*static* `add_ca_to_dir`(*ca\_list*, *dir\_path=None*, *template\_dir=None*)[[source]](_modules/pdm/utils/X509.html#X509Utils.add_ca_to_dir)[¶](#pdm.utils.X509.X509Utils.add_ca_to_dir "Permalink to this definition")

Adds a CA list to OpenSSL style hash dir.

ca\_list - A list of strings, each one a PEM encoded CA certificate

to be written to the directory.

dir\_path - The directory to write the files to. If not specified a

temporary directory will be created.

Note: The caller must delete the directory when they are

> 

> finished with it to prevent cluttering up /tmp.

template\_dir - Template directory path (str) to use as the initial

contents of the CA dir if we create it. If dir\_path

is not none, then this option is ignored.

Set to None (default) to disable this feature.

Returns the directory path to the CA dir.

*static* `convert_dn`(*input\_dn*, *input\_sep*, *output\_sep*, *with\_space*)[[source]](_modules/pdm/utils/X509.html#X509Utils.convert_dn)[¶](#pdm.utils.X509.X509Utils.convert_dn "Permalink to this definition")

Converts a DN from one format to another.

input\_dn is the string to convert.

input\_sep & output\_sep are the seperators to use between segs.

with\_space is a bool, True to include spaces around the = sign.

*static* `get_cert_expiry`(*cert\_pem*)[[source]](_modules/pdm/utils/X509.html#X509Utils.get_cert_expiry)[¶](#pdm.utils.X509.X509Utils.get_cert_expiry "Permalink to this definition")

Gets the expiry date of a given X.509 public certificate

in PEM format.

cert\_pem - Input cert PEM string.

Returns a datetime object of the expiry time.

*static* `normalise_dn`(*dn\_str*)[[source]](_modules/pdm/utils/X509.html#X509Utils.normalise_dn)[¶](#pdm.utils.X509.X509Utils.normalise_dn "Permalink to this definition")

Converts a DN from any standard format (RFC2253, OpenSSL) with any

spacing into plain RFC2253 format with “readable” spacing.

Returns a string.

*static* `openssl_to_rfc`(*input\_dn*)[[source]](_modules/pdm/utils/X509.html#X509Utils.openssl_to_rfc)[¶](#pdm.utils.X509.X509Utils.openssl_to_rfc "Permalink to this definition")

This converts an OpenSSL style DN: /C=XX/L=YY/…

to an RFC2253 style one: C = XX, L = YY, …

If the input doesn’t start with / character (i.e. input

is probably already RFC2253) then input is returned.

*static* `rfc_to_openssl`(*input\_dn*)[[source]](_modules/pdm/utils/X509.html#X509Utils.rfc_to_openssl)[¶](#pdm.utils.X509.X509Utils.rfc_to_openssl "Permalink to this definition")

This convert an RFC style DN: C = XX, L = YY, …

to an OpenSSL style one: /C=XX/L=YY,…

If the input already starts with a / then it is

directly returned (as it’s probably already in the

correct format.

*static* `str_to_x509name`(*dn\_val*)[[source]](_modules/pdm/utils/X509.html#X509Utils.str_to_x509name)[¶](#pdm.utils.X509.X509Utils.str_to_x509name "Permalink to this definition")

Converts a raw DN string into an X509\_Name object.

Input DN can be in OpenSSL or RFC2253 format.

*static* `write_policy`(*ca\_pem*, *target\_file*)[[source]](_modules/pdm/utils/X509.html#X509Utils.write_policy)[¶](#pdm.utils.X509.X509Utils.write_policy "Permalink to this definition")

Writes a signing policy for CA described by ca\_pem

into the file with filename target\_file.

The policy file will allow any issued certs to be in

/OU=Users or /OU=Hosts.

Returns None.

*static* `x509name_to_str`(*x509\_name*)[[source]](_modules/pdm/utils/X509.html#X509Utils.x509name_to_str)[¶](#pdm.utils.X509.X509Utils.x509name_to_str "Permalink to this definition")

Converts an X509\_Name object to a plain string.

The output string will be in RFC2253 format with

“readable” spacing…

##### pdm.utils.config module[¶](#module-pdm.utils.config "Permalink to this headline")

Configuration System Module.

*class* `pdm.utils.config.``ConfigSystem`[[source]](_modules/pdm/utils/config.html#ConfigSystem)[¶](#pdm.utils.config.ConfigSystem "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Config system singleton.

`config`[¶](#pdm.utils.config.ConfigSystem.config "Permalink to this definition")

The current state of the configuration.

`get_section`(*section*)[[source]](_modules/pdm/utils/config.html#ConfigSystem.get_section)[¶](#pdm.utils.config.ConfigSystem.get_section "Permalink to this definition")

Return a given section.

`sections`[¶](#pdm.utils.config.ConfigSystem.sections "Permalink to this definition")

Get list of sections.

`setup`(*filenames='~/.config/pdm/pdm.conf'*, *ignore\_errors=False*)[[source]](_modules/pdm/utils/config.html#ConfigSystem.setup)[¶](#pdm.utils.config.ConfigSystem.setup "Permalink to this definition")

Setup the configuration system.

`pdm.utils.config.``getConfig`(*section*)[[source]](_modules/pdm/utils/config.html#getConfig)[¶](#pdm.utils.config.getConfig "Permalink to this definition")

Get config helper function.

Return the config for the given section.

##### pdm.utils.daemon module[¶](#module-pdm.utils.daemon "Permalink to this headline")

Daemon Utility Module.

*class* `pdm.utils.daemon.``Daemon`(*pidfile*, *target*, *args=None*, *kwargs=None*, *\*\*options*)[[source]](_modules/pdm/utils/daemon.html#Daemon)[¶](#pdm.utils.daemon.Daemon "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Daemon Base.

This daemon base class is designed to work on LINUX systems only.

The design borrows heavily from Chad J. Schroeder’s recipe:

<http://code.activestate.com/recipes/278731-creating-a-daemon-the-python-way>

as well as taking guidance from PEP 3143 and inspiration from daemonize:

<https://github.com/thesharp/daemonize>

Example:

>>> import logging

>>> from pdm.utils import Daemon

>>>

>>> def my\_func(a):

>>> logging.getLogger(‘my\_func’).info(“In daemon: %s”, a)

>>>

>>> Daemon(pidfile=’daemon.pid’, target=my\_func, args=(‘Hello World’,)).start()

`exit`()[[source]](_modules/pdm/utils/daemon.html#Daemon.exit)[¶](#pdm.utils.daemon.Daemon.exit "Permalink to this definition")

Called on daemon exit.

`pid`[¶](#pdm.utils.daemon.Daemon.pid "Permalink to this definition")

Get the pid of the running daemon.

`start`()[[source]](_modules/pdm/utils/daemon.html#Daemon.start)[¶](#pdm.utils.daemon.Daemon.start "Permalink to this definition")

Start daemon process.

`terminate`(*\*\_*)[[source]](_modules/pdm/utils/daemon.html#Daemon.terminate)[¶](#pdm.utils.daemon.Daemon.terminate "Permalink to this definition")

Called on receiving SIGTERM.

##### pdm.utils.db module[¶](#module-pdm.utils.db "Permalink to this headline")

Database Utility Module.

`pdm.utils.db.``managed_session`(*\*args*, *\*\*kwds*)[[source]](_modules/pdm/utils/db.html#managed_session)[¶](#pdm.utils.db.managed_session "Permalink to this definition")

Managed database session context.

request - A flask request object containing a db attribute.

message - The message to log if an error occurs, also returned

> 

> to the user if abort is called.

logger - If not None, log the message to this logger.

http\_error\_code - If set, a Flask abort exception is raised

> 

> with this code & the provided message.

If http\_error\_code is unset, the internal exception is re-raised.

##### pdm.utils.hashing module[¶](#module-pdm.utils.hashing "Permalink to this headline")

Utilities for hashing things.

`pdm.utils.hashing.``check_hash`(*hash\_in*, *password*)[[source]](_modules/pdm/utils/hashing.html#check_hash)[¶](#pdm.utils.hashing.check_hash "Permalink to this definition")

Checks a password against a hashed version to see if they

match.

hash\_in - A salted password hash (such as that from hash\_pass)

password - A password string in to compare.

Returns True is the password matches the hash.

`pdm.utils.hashing.``get_salt`()[[source]](_modules/pdm/utils/hashing.html#get_salt)[¶](#pdm.utils.hashing.get_salt "Permalink to this definition")

Returns a new salt.

`pdm.utils.hashing.``hash_pass`(*password*, *salt=None*)[[source]](_modules/pdm/utils/hashing.html#hash_pass)[¶](#pdm.utils.hashing.hash_pass "Permalink to this definition")

A helper function to convert a password to a hash.

password - Input password string to hash.

salt - (Optional) Use fixed salt instead of random one.

Returns a string of the hashed password.

Note: The hashes are salted and are therefore different

> 

> every time. Use check\_hash to check an existing hash

> against a password.

##### pdm.utils.lockfile module[¶](#module-pdm.utils.lockfile "Permalink to this headline")

Lock file utilities.

*exception* `pdm.utils.lockfile.``AlreadyLockedError`(*\*args*, *\*\*kwargs*)[[source]](_modules/pdm/utils/lockfile.html#AlreadyLockedError)[¶](#pdm.utils.lockfile.AlreadyLockedError "Permalink to this definition")

Bases: `exceptions.IOError`

Lockfile already locked error.

*class* `pdm.utils.lockfile.``PIDLockFile`(*filename*, *lock\_fail\_log=True*)[[source]](_modules/pdm/utils/lockfile.html#PIDLockFile)[¶](#pdm.utils.lockfile.PIDLockFile "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Open a lockfile.

Opens a file and try to acquire a filesystem lock on said file.

If successful write the current processes pid into the file.

`fileno`[¶](#pdm.utils.lockfile.PIDLockFile.fileno "Permalink to this definition")

Return the open lockfiles file descriptor.

`name`[¶](#pdm.utils.lockfile.PIDLockFile.name "Permalink to this definition")

Return the name of the lockfile.

`update_pid`()[[source]](_modules/pdm/utils/lockfile.html#PIDLockFile.update_pid)[¶](#pdm.utils.lockfile.PIDLockFile.update_pid "Permalink to this definition")

Update the pid written into the lockfile.

This is usefull for daemon setup where a new

process is forked twice.

##### pdm.utils.singleton module[¶](#module-pdm.utils.singleton "Permalink to this headline")

Singleton Utility Module.

*exception* `pdm.utils.singleton.``InstantiationError`(*\*args*, *\*\*kwargs*)[[source]](_modules/pdm/utils/singleton.html#InstantiationError)[¶](#pdm.utils.singleton.InstantiationError "Permalink to this definition")

Bases: `exceptions.RuntimeError`

Instantiation exception.

*class* `pdm.utils.singleton.``SingletonMeta`[[source]](_modules/pdm/utils/singleton.html#SingletonMeta)[¶](#pdm.utils.singleton.SingletonMeta "Permalink to this definition")

Bases: [`type`](https://docs.python.org/3/library/functions.html#type "(in Python v3.8)")

Singleton MetaClass.

This can be used either with the static variable \_\_metaclass\_\_

or indirectly through the singleton class decorator see help(singleton).

Example:

>>> class test(object):

>>> \_\_metaclass\_\_ = SingletonMeta

`get_instance`(*\*args*, *\*\*kwargs*)[[source]](_modules/pdm/utils/singleton.html#SingletonMeta.get_instance)[¶](#pdm.utils.singleton.SingletonMeta.get_instance "Permalink to this definition")

Get instance.

`pdm.utils.singleton.``singleton`(*cls*)[[source]](_modules/pdm/utils/singleton.html#singleton)[¶](#pdm.utils.singleton.singleton "Permalink to this definition")

Singleton class decorator.

A class decorator rendering the decorated class a singleton.

Example:

>>> @singleton

>>> class test(object):

>>> pass

##### pdm.utils.sshkey module[¶](#module-pdm.utils.sshkey "Permalink to this headline")

Tools for handling SSH keys.

*class* `pdm.utils.sshkey.``SSHKeyUtils`[[source]](_modules/pdm/utils/sshkey.html#SSHKeyUtils)[¶](#pdm.utils.sshkey.SSHKeyUtils "Permalink to this definition")

Bases: [`object`](https://docs.python.org/3/library/functions.html#object "(in Python v3.8)")

Utilities for working with SSH keys.

`DEF_ENC_ALGO` *= 'aes\_256\_cbc'*[¶](#pdm.utils.sshkey.SSHKeyUtils.DEF_ENC_ALGO "Permalink to this definition")

`DEF_EXPONENT` *= 5*[¶](#pdm.utils.sshkey.SSHKeyUtils.DEF_EXPONENT "Permalink to this definition")

`DEF_NUM_BITS` *= 2048*[¶](#pdm.utils.sshkey.SSHKeyUtils.DEF_NUM_BITS "Permalink to this definition")

*static* `gen_rsa_keypair`(*passphrase=None*, *comment=''*, *bits=2048*)[[source]](_modules/pdm/utils/sshkey.html#SSHKeyUtils.gen_rsa_keypair)[¶](#pdm.utils.sshkey.SSHKeyUtils.gen_rsa_keypair "Permalink to this definition")

Generates a new SSH key-pair, encrypted with the

given passphrase.

If passphrase is None then the output is unencrypted.

Returns a tuple of two strings: (pub, key)

> 

> 

> pub is an ssh-rsa encoded public string.

> (RFC4253 encoded)

> 

> key is a PEM encoded private key.

> 

> 

> 

Returns (pub, key)

*static* `remove_pass`(*key\_in*, *passphrase=None*)[[source]](_modules/pdm/utils/sshkey.html#SSHKeyUtils.remove_pass)[¶](#pdm.utils.sshkey.SSHKeyUtils.remove_pass "Permalink to this definition")

Removes the password from an SSH key.

key\_in - The PEM encoded input key.

passphrase - The password of the input key.

Returns PEM encoded key with no password.

#### pdm.workqueue package[¶](#module-pdm.workqueue "Permalink to this headline")

Workqueue Package.

##### Submodules[¶](#submodules "Permalink to this headline")

##### pdm.workqueue.WorkqueueClient module[¶](#pdm-workqueue-workqueueclient-module "Permalink to this headline")

*class* `pdm.workqueue.WorkqueueClient.``WorkqueueClient`[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient "Permalink to this definition")

Bases: `pdm.framework.RESTClient.RESTClient`

A client class for WorkqueueService.

`copy`(*src\_siteid*, *src\_filepath*, *dst\_siteid*, *dst\_filepath*, *max\_tries=2*, *priority=5*, *protocol=<JobProtocol.GRIDFTP: 0>*, *\*\*kwargs*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.copy)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.copy "Permalink to this definition")

Copy a one path to another.

Variable keyword args are passed directly on to the worker script as extra\_opts.

| Parameters: | * **src\_siteid** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id of the site containing the path to be copied from.

* **src\_filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The path to copy from.

* **dst\_siteid** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id of the site containing the path to be copied to.

* **dst\_filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The path to copy to.

* **max\_tries** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The maximum number of times to attempt the copy. (default: 2)

* **priority** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The DIRAC priority (0-9) of the job. (default: 5)

* **protocol** ([*JobProtocol*](index.html#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol")) – The protocol type to use. (default: GRIDFTP)

 |

| Returns: | The job object as stored in the workqueue database. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`element`(*job\_id*, *element\_id*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.element)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.element "Permalink to this definition")

Get a job element by id.

| Parameters: | * **job\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job to get.

* **element\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job element to get.

 |

| Returns: | Representation of job element. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`elements`(*job\_id*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.elements)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.elements "Permalink to this definition")

Get a job elements for job with given id.

| Parameters: | **job\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job containing elements to get. |

| Returns: | the jobs elements as dicts. |

| Return type: | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.8)") |

`job`(*job\_id*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.job)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.job "Permalink to this definition")

Get a job by id.

| Parameters: | **job\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job to get. |

| Returns: | Representation of job. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`jobs`()[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.jobs)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.jobs "Permalink to this definition")

Get all jobs for a user.

| Returns: | The users jobs as dicts. |

| Return type: | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.8)") |

`list`(*siteid*, *filepath*, *max\_tries=2*, *priority=5*, *protocol=<JobProtocol.GRIDFTP: 0>*, *\*\*kwargs*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.list)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.list "Permalink to this definition")

List a given path.

Variable keyword args are passed directly on to the worker script as extra\_opts.

| Parameters: | * **siteid** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id of the site containing the path to be listed.

* **filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The path to list.

* **max\_tries** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The maximum number of times to attempt the listing. (default: 2)

* **priority** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The DIRAC priority (0-9) of the job. (default: 5)

* **protocol** ([*JobProtocol*](index.html#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol")) – The protocol type to use. (default: GRIDFTP)

 |

| Returns: | The job object as stored in the workqueue database. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`mkdir`(*siteid*, *filepath*, *max\_tries=2*, *priority=5*, *protocol=<JobProtocol.GRIDFTP: 0>*, *\*\*kwargs*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.mkdir)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.mkdir "Permalink to this definition")

Make a directory.

Variable keyword args are passed directly on to the worker script as extra\_opts.

| Parameters: | * **siteid** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id of the site containing the dir path to be created.

* **filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The dir path to create.

* **credentials** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – Token allowing access to the users credentials from the cred service.

* **max\_tries** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The maximum number of times to attempt the mkdir. (default: 2)

* **priority** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The DIRAC priority (0-9) of the job. (default: 5)

* **protocol** ([*JobProtocol*](index.html#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol")) – The protocol type to use. (default: GRIDFTP)

 |

| Returns: | The job object as stored in the workqueue database. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`output`(*job\_id*, *element\_id=None*, *attempt=None*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.output)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.output "Permalink to this definition")

Get job output.

Gets the output for all attempts, for all elements of the given job if they are ready. The

optional parameter element\_id allows the user to get the output for a given job element,

while attempt allows the user to get the output for a given attempt of a specific element.

Note

Specifying attempt without an element\_id is an error and will not return that attempt

for all elements but will instead be ignored and the user will get the output for all

attempts, for all elements.

| Parameters: | * **job\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job to fetch latest output from.

* **element\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job element to fetch latest output from.

(default: None = all)

* **attempt** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The attempt number to get the output from. This may be negative in order

to index from the back. (default: None = all)

 |

| Returns: | 

List of lists with the outer list being the list of elements for the given job,

or a single element if element\_id is specified. The inner list represents the

attempts, or a single attempt if attempt is given. Each attempt is a dictionary

with keys (jobid, elementid, attempt, type, status, log, (listing)). Log is the

contents of the log file for that attempt. If the job element in question was a

LIST type job then there will be the additional key “listing” which will be a JSON

encoded dictionary of form {directory: [files],…}.

 |

| Return type: | [list](https://docs.python.org/3/library/stdtypes.html#list "(in Python v3.8)") |

Examples

```

>>> WorkqueueClient().output(12)

[

 [

 {

 "jobid": 12,

 "elementid": 0,

 "attempt": 1,

 "type": "LIST",

 "status": "DONE",

 "log": "The output from the LIST command for file1 run on the worker",

 "listing": {"root": ["file1", "file2"]}

 }

 ],

 [

 {

 "jobid": 12,

 "elementid": 1,

 "attempt": 1,

 "type": "COPY",

 "status": "FAILED",

 "log": "The output from the COPY command run on the worker"

 },

 {

 "jobid": 12,

 "elementid": 1,

 "attempt": 2,

 "type": "COPY",

 "status": "DONE",

 "log": "The output from the COPY command run on the worker"

 }

 ]

]

```

```

>>> WorkqueueClient().output(12, 1)

[

 [

 {

 "jobid": 12,

 "elementid": 1,

 "attempt": 1,

 "type": "COPY",

 "status": "FAILED",

 "log": "The output from the COPY command run on the worker"

 },

 {

 "jobid": 12,

 "elementid": 1,

 "attempt": 2,

 "type": "COPY",

 "status": "DONE",

 "log": "The output from the COPY command run on the worker"

 }

 ]

]

```

```

>>> WorkqueueClient().output(12, 1, 1)

[

 [

 {

 "jobid": 12,

 "elementid": 1,

 "attempt": 1,

 "type": "COPY",

 "status": "FAILED",

 "log": "The output from the COPY command run on the worker"

 }

 ]

]

```

`remove`(*siteid*, *filepath*, *max\_tries=2*, *priority=5*, *protocol=<JobProtocol.GRIDFTP: 0>*, *\*\*kwargs*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.remove)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.remove "Permalink to this definition")

Remove a given path.

Variable keyword args are passed directly on to the worker script as extra\_opts.

| Parameters: | * **siteid** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id of the site containing the path to be removed.

* **filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The path to remove.

* **credentials** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – Token allowing access to the users credentials from the cred service.

* **max\_tries** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The maximum number of times to attempt the remove. (default: 2)

* **priority** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The DIRAC priority (0-9) of the job. (default: 5)

* **protocol** ([*JobProtocol*](index.html#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol")) – The protocol type to use. (default: GRIDFTP)

 |

| Returns: | The job object as stored in the workqueue database. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`rename`(*siteid*, *src\_filepath*, *dst\_filepath*, *max\_tries=2*, *priority=5*, *protocol=<JobProtocol.GRIDFTP: 0>*, *\*\*kwargs*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.rename)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.rename "Permalink to this definition")

Rename a filepath.

Variable keyword args are passed directly on to the worker script as extra\_opts.

| Parameters: | * **siteid** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id of the site containing the filepath to be renamed.

* **src\_filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The filepath to rename.

* **dst\_filepath** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.8)")) – The new filepath.

* **max\_tries** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The maximum number of times to attempt the rename. (default: 2)

* **priority** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The DIRAC priority (0-9) of the job. (default: 5)

* **protocol** ([*JobProtocol*](index.html#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol")) – The protocol type to use. (default: GRIDFTP)

 |

| Returns: | The job object as stored in the workqueue database. |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

`status`(*job\_id*, *element\_id=None*)[[source]](_modules/pdm/workqueue/WorkqueueClient.html#WorkqueueClient.status)[¶](#pdm.workqueue.WorkqueueClient.WorkqueueClient.status "Permalink to this definition")

Get a jobs status.

This returns the human readable status rather than the integer code. This

function will also retrieve the number of attempts the system has made for the

given job.

| Parameters: | * **job\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job to query.

* **element\_id** ([*int*](https://docs.python.org/3/library/functions.html#int "(in Python v3.8)")) – The id number of the job element to query.

 |

| Returns: | Representation of the status with keys (jobid, status, attempts(element only) ) |

| Return type: | [dict](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.8)") |

---

##### pdm.workqueue.WorkqueueDB module[¶](#pdm-workqueue-workqueuedb-module "Permalink to this headline")

*class* `pdm.workqueue.WorkqueueDB.``JobType`[[source]](_modules/pdm/workqueue/WorkqueueDB.html#JobType)[¶](#pdm.workqueue.WorkqueueDB.JobType "Permalink to this definition")

Bases: `pdm.workqueue.WorkqueueDB.EnumBase`

Job type enum.

`COPY` *= 1*[¶](#pdm.workqueue.WorkqueueDB.JobType.COPY "Permalink to this definition")

`LIST` *= 0*[¶](#pdm.workqueue.WorkqueueDB.JobType.LIST "Permalink to this definition")

`MKDIR` *= 4*[¶](#pdm.workqueue.WorkqueueDB.JobType.MKDIR "Permalink to this definition")

`REMOVE` *= 2*[¶](#pdm.workqueue.WorkqueueDB.JobType.REMOVE "Permalink to this definition")

`RENAME` *= 3*[¶](#pdm.workqueue.WorkqueueDB.JobType.RENAME "Permalink to this definition")

*class* `pdm.workqueue.WorkqueueDB.``JobProtocol`[[source]](_modules/pdm/workqueue/WorkqueueDB.html#JobProtocol)[¶](#pdm.workqueue.WorkqueueDB.JobProtocol "Permalink to this definition")

Bases: `pdm.workqueue.WorkqueueDB.EnumBase`

Job protocol enum.

`DUMMY` *= 2*[¶](#pdm.workqueue.WorkqueueDB.JobProtocol.DUMMY "Permalink to this definition")

`GRIDFTP` *= 0*[¶](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "Permalink to this definition")

`SSH` *= 1*[¶](#pdm.workqueue.WorkqueueDB.JobProtocol.SSH "Permalink to this definition")

*class* `pdm.workqueue.WorkqueueDB.``JobStatus`[[source]](_modules/pdm/workqueue/WorkqueueDB.html#JobStatus)[¶](#pdm.workqueue.WorkqueueDB.JobStatus "Permalink to this definition")

Bases: `pdm.workqueue.WorkqueueDB.EnumBase`

Job status enum.

`DONE` *= 1*[¶](#pdm.workqueue.WorkqueueDB.JobStatus.DONE "Permalink to this definition")

`FAILED` *= 2*[¶](#pdm.workqueue.WorkqueueDB.JobStatus.FAILED "Permalink to this definition")

`NEW` *= 0*[¶](#pdm.workqueue.WorkqueueDB.JobStatus.NEW "Permalink to this definition")

`RUNNING` *= 4*[¶](#pdm.workqueue.WorkqueueDB.JobStatus.RUNNING "Permalink to this definition")

`SUBMITTED` *= 3*[¶](#pdm.workqueue.WorkqueueDB.JobStatus.SUBMITTED "Permalink to this definition")

###### Job DB model[¶](#job-db-model "Permalink to this headline")

```

"""Initialisation."""

class Job(db\_base, JSONMixin, SmartColumnAwareMixin):

    """Jobs table."""

    \_\_tablename\_\_ = 'jobs'

    id = Column(Integer, primary\_key=True)  # pylint: disable=invalid-name

    user\_id = SmartColumn(Integer, nullable=False, allowed=True, required=True)

    log\_uid = SmartColumn(String(36), nullable=False, default=lambda: str(uuid.uuid4()))

    src\_siteid = SmartColumn(Integer, nullable=False, allowed=True, required=True)

    dst\_siteid = SmartColumn(Integer, allowed=True)

    src\_filepath = SmartColumn(TEXT, nullable=False, required=True, allowed=True)

    dst\_filepath = SmartColumn(TEXT, allowed=True)

    extra\_opts = SmartColumn(PickleType, allowed=True)

    src\_credentials = SmartColumn(TEXT, allowed=True)

    dst\_credentials = SmartColumn(TEXT, allowed=True)

    timestamp = Column(TIMESTAMP, nullable=False,

                       default=datetime.utcnow, onupdate=datetime.utcnow)

    priority = SmartColumn(SmallInteger,

                           CheckConstraint('priority in {0}'.format(tuple(xrange(10)))),

                           nullable=False, allowed=True, default=5)

    type = SmartColumn(SmallInteger,  # pylint: disable=invalid-name

                       CheckConstraint('type in {0}'.format(JobType.values())),

                       nullable=False, allowed=True, required=True)

    protocol = SmartColumn(SmallInteger,

                           CheckConstraint('protocol in {0}'.format(JobProtocol.values())),

                           nullable=False, allowed=True, default=JobProtocol.GRIDFTP)

    status = Column(SmallInteger,

                    CheckConstraint('status in {0}'.format(JobStatus.values())),

                    nullable=False, default=JobStatus.NEW)

    elements = relationship("JobElement", back\_populates="job",

```

###### JobElement DB model[¶](#jobelement-db-model "Permalink to this headline")

```

class JobElement(db\_base, JSONMixin, SmartColumnAwareMixin):

    """Jobs table."""

    \_\_tablename\_\_ = 'jobelements'

    \_\_table\_args\_\_ = (

        CheckConstraint('attempts <= max\_tries'),

    )

    # pylint: disable=invalid-name

    id = SmartColumn(Integer, primary\_key=True, required=True, allowed=True)

    job\_id = Column(Integer, ForeignKey('jobs.id'), primary\_key=True)

    job = relationship("Job", back\_populates="elements")

    src\_filepath = SmartColumn(TEXT, nullable=False, required=True, allowed=True)

    dst\_filepath = SmartColumn(TEXT, allowed=True)

    listing = Column(PickleType, nullable=True)

    monitoring\_info = Column(PickleType, nullable=True)

    size = SmartColumn(Integer, nullable=False, default=0, allowed=True)

    max\_tries = SmartColumn(SmallInteger, nullable=False, default=2, allowed=True)

    attempts = Column(SmallInteger, nullable=False, default=0)

    timestamp = Column(TIMESTAMP, nullable=False,

                       default=datetime.utcnow, onupdate=datetime.utcnow)

    type = SmartColumn(SmallInteger,  # pylint: disable=invalid-name

                       CheckConstraint('type in {0}'.format(JobType.values())),

                       nullable=False, allowed=True, required=True)

    status = Column(SmallInteger,

```

---

##### pdm.workqueue.WorkqueueService module[¶](#pdm-workqueue-workqueueservice-module "Permalink to this headline")

Note

All URLs are to be prefixed with **/workqueue/api/v1.0**. If in doubt look at the **Example request** for your desired api.

`GET` `/jobs`[¶](#get--jobs "Permalink to this definition")

Get all registered jobs for user or empty array.

| Request Headers: |

| --- |

|  | * [Accept](https://tools.ietf.org/html/rfc7231#section-5.3.2) – the response content type depends on

*Accept* header

 |

| Response Headers: |

|  | * [Content-Type](https://tools.ietf.org/html/rfc7231#section-3.1.1.5) – this depends on *Accept*

header of request

 |

| Response JSON Array of Objects: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

[

  {

    "id": 12345,

    "user\_id": 123,

    "src\_siteid": 13,

    "dst\_siteid": 15,

    "src\_filepath": "~/file1.txt",

    "dst\_filepath": "~/file2.txt",

    "type": "COPY",

    "status": "DONE",

    "extra\_opts": {},

    "priority": 5,

    "protocol": "GRIDFTP",

    "log\_uid": "somelonghash",

    "timestamp": "2012-03-21T13:35"

  },

]

```

`GET` `/jobs/<int:job_id>`[¶](#get--jobs--int-job_id- "Permalink to this definition")

Get specific job with id job\_id.

| Response JSON Object: |

| --- |

|  | * **id** (*int*) – job id, this will be job\_id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id found

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12345 HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 12345,

  "user\_id": 123,

  "src\_siteid": 13,

  "dst\_siteid": 15,

  "src\_filepath": "~/file1.txt",

  "dst\_filepath": "~/file2.txt",

  "type": "COPY",

  "status": "DONE",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

`GET` `/jobs/<int:job_id>/elements`[¶](#get--jobs--int-job_id--elements "Permalink to this definition")

Get the job elements for job with id job\_id

| Response JSON Array of Objects: |

| --- |

|  | * **id** (*int*) – job element id

* **job\_id** (*int*) – parent job’s id, this will be job\_id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **size** (*int*) – the size of the file on disk

* **max\_tries** (*int*) – maximum number of times to try this element

* **attempts** (*int*) – number of times the element has been processed

* **type** (*string*) – the job element’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job element’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

* **listing** (*object*) – listing of a root directory in the form {“root”: [“file1”, “file2”,],}

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12345/elements HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

[

  {

    "id": 1,

    "job\_id": 12345,

    "src\_filepath": "~/file1.txt",

    "dst\_filepath": "~/file2.txt",

    "size": 123354523,

    "max\_tries": 2,

    "attempts": 1,

    "type": "COPY",

    "status": "DONE",

    "timestamp": "2012-03-21T13:35",

    "listing": {"root": ["file1", "file2"]}

  },

]

```

`GET` `/jobs/<int:job_id>/elements/<int:element_id>`[¶](#get--jobs--int-job_id--elements--int-element_id- "Permalink to this definition")

Get element element\_id for job with id job\_id

| Response JSON Object: |

| --- |

|  | * **id** (*int*) – job element id, this will be element\_id

* **job\_id** (*int*) – parent job’s id, this will be job\_id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **size** (*int*) – the size of the file on disk

* **max\_tries** (*int*) – maximum number of times to try this element

* **attempts** (*int*) – number of times the element has been processed

* **type** (*string*) – the job element’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job element’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

* **listing** (*object*) – listing of a root directory in the form {“root”: [“file1”, “file2”,],}

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id or element with id element\_id found

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12345/elements/1 HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "job\_id": 12345,

  "src\_filepath": "~/file1.txt",

  "dst\_filepath": "~/file2.txt",

  "size": 123354523,

  "max\_tries": 2,

  "attempts": 1,

  "type": "COPY",

  "status": "DONE",

  "timestamp": "2012-03-21T13:35",

  "listing": {"root": ["file1", "file2"]}

}

```

`GET` `/jobs/<int:job_id>/output`[¶](#get--jobs--int-job_id--output "Permalink to this definition")

Get the output from all attempts of all elements for a job with given job\_id. Outer array is list of elements while inner array is list of attempts as JSON objects.

Note

Only *LIST* type jobs get an extra listing key (see example below).

| Response JSON Array of Objects: |

| --- |

|  | * **jobid** (*int*) – the id of the parent job requested, this will be job\_id

* **elementid** (*int*) – the id of the element

* **attempt** (*int*) – the latest attempt number

* **type** (*string*) – the job element’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job element’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **log** (*string*) – the job element’s output (comming from the command execution script run on the worker)

* **listing** (*object*) – listing of a root directory in the form {“root”: [“file1”, “file2”,],} (**Only** for *LIST* type jobs)

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id found

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12/output HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

[

  [

    {

      "jobid": 12,

      "elementid": 0,

      "attempt": 1,

      "type": "LIST",

      "status": "DONE",

      "log": "The output from the LIST command for file1 run on the worker",

      "listing": {"root": ["file1", "file2"]}

    }

  ],

  [

    {

      "jobid": 12,

      "elementid": 1,

      "attempt": 1,

      "type": "COPY",

      "status": "FAILED",

      "log": "The output from the COPY command run on the worker"

    },

    {

      "jobid": 12,

      "elementid": 1,

      "attempt": 2,

      "type": "COPY",

      "status": "DONE",

      "log": "The output from the COPY command run on the worker"

    }

  ]

]

```

`GET` `/jobs/<int:job_id>/elements/<int:element_id>/output`[¶](#get--jobs--int-job_id--elements--int-element_id--output "Permalink to this definition")

Get the output from all attempts for element element\_id of a job with given job\_id

Note

Only *LIST* type jobs get an extra listing key (see example below).

| Response JSON Array of Objects: |

| --- |

|  | * **jobid** (*int*) – the id of the parent job requested, this will be job\_id

* **elementid** (*int*) – the id of the element, this will be element\_id

* **attempt** (*int*) – the attempt number

* **type** (*string*) – the job element’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job element’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **log** (*string*) – the job element’s output (comming from the command execution script run on the worker)

* **listing** (*object*) – listing of a root directory in the form {“root”: [“file1”, “file2”,],} (**Only** for *LIST* type jobs)

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id or element with id element\_id found. Also returned if no attempts have yet been made for specified element

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12/elements/1/output HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

[

  {

    "jobid": 12,

    "elementid": 1,

    "attempt": 1,

    "type": "COPY",

    "status": "FAILED",

    "log": "The output from the copy command run on the worker"

  },

  {

    "jobid": 12,

    "elementid": 1,

    "attempt": 2,

    "type": "COPY",

    "status": "DONE",

    "log": "The output from the copy command run on the worker"

  },

]

```

`GET` `/jobs/<int:job_id>/elements/<int:element_id>/output/<int:attempt>`[¶](#get--jobs--int-job_id--elements--int-element_id--output--int-attempt- "Permalink to this definition")

Get the output of attempt attempt for element element\_id of a job with given job\_id. attempt may be a negative integer in order to index from the back.

Note

Only *LIST* type jobs get an extra listing key (see example below).

| Response JSON Object: |

| --- |

|  | * **jobid** (*int*) – the id of the parent job requested, this will be job\_id

* **elementid** (*int*) – the id of the element, this will be element\_id

* **attempt** (*int*) – the requested attempt, this will be attempt

* **type** (*string*) – the job element’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job element’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **log** (*string*) – the job element’s output (comming from the command execution script run on the worker)

* **listing** (*object*) – listing of a root directory in the form {“root”: [“file1”, “file2”,],} (**Only** for *LIST* type jobs)

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – attempt is not an integer

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id or element with id element\_id or attempt attempt found. Also returned if no attempts have yet been made for specified element

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – couldn’t find the requested output file for attempt attempt on disk.

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12/elements/1/output/1 HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "jobid": 12,

  "elementid": 1,

  "attempt": 1,

  "type": "COPY",

  "status": "FAILED",

  "log": "The output from the copy command run on the worker"

}

```

`GET` `/jobs/<int:job_id>/status`[¶](#get--jobs--int-job_id--status "Permalink to this definition")

Get the status of job with id job\_id

| Response JSON Object: |

| --- |

|  | * **jobid** (*int*) – the id of the job requested, this will be job\_id

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id found

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12/status HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "jobid": 12,

  "status": "DONE"

}

```

`GET` `/jobs/<int:job_id>/elements/<int:element_id>/status`[¶](#get--jobs--int-job_id--elements--int-element_id--status "Permalink to this definition")

Get the status of element element\_id for job with id job\_id

| Response JSON Object: |

| --- |

|  | * **jobid** (*int*) – the id of the parent job requested, this will be job\_id

* **elementid** (*int*) – the id of the element, this will be element\_id

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **attempts** (*int*) – the number of times the element has been processed

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) – no job with id job\_id or element with id element\_id found

 |

**Example request**:

```

GET /workqueue/api/v1.0/jobs/12/elements/1/status HTTP/1.1

Host: example.com

Accept: application/json

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "jobid": 12,

  "elementid": 1,

  "status": "DONE",

  "attempts": 2

}

```

`POST` `/jobs`[¶](#post--jobs "Permalink to this definition")

Register a new job.

| Request JSON Object: |

| --- |

|  | * **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id (**Only** for COPY type jobs)

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem (**Only** for COPY/RENAME type jobs)

* **type** (*int/string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts (optional)

* **priority** (*int*) – the job’s priority 0-9 (optional default: 5)

* **protocol** (*int/string*) – the protocol to use for the job (optional default: [`GRIDFTP`](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP"))

 |

| Response JSON Object: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

 |

**Example request**:

```

POST /workqueue/api/v1.0/jobs HTTP/1.1

Host: example.com

Accept: application/json

Data: {

        "src\_siteid": 12,

        "src\_filepath": "somefile",

        "type": "LIST",

      }

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "user\_id": 123,

  "src\_siteid": 12,

  "src\_filepath": "somefile",

  "type": "LIST",

  "status": "SUBMITTED",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

`POST` `/list`[¶](#post--list "Permalink to this definition")

Register a listing job.

| Request JSON Object: |

| --- |

|  | * **src\_siteid** (*int*) – source site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts (optional)

* **priority** (*int*) – the job’s priority 0-9 (optional default: 5)

* **protocol** (*int/string*) – the protocol to use for the job (optional default: [`GRIDFTP`](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP"))

 |

| Response JSON Object: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

 |

**Example request**:

```

POST /workqueue/api/v1.0/list HTTP/1.1

Host: example.com

Accept: application/json

Data: {

        "src\_siteid": 12,

        "src\_filepath": "somefile"

      }

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "user\_id": 123,

  "src\_siteid": 12,

  "src\_filepath": "somefile",

  "type": "LIST",

  "status": "SUBMITTED",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

`POST` `/copy`[¶](#post--copy "Permalink to this definition")

Register a copy job.

| Request JSON Object: |

| --- |

|  | * **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts (optional)

* **priority** (*int*) – the job’s priority 0-9 (optional default: 5)

* **protocol** (*int/string*) – the protocol to use for the job (optional default: [`GRIDFTP`](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP"))

 |

| Response JSON Object: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

 |

**Example request**:

```

POST /workqueue/api/v1.0/copy HTTP/1.1

Host: example.com

Accept: application/json

Data: {

        "src\_siteid": 12,

        "dst\_siteid": 14,

        "src\_filepath": "somefile",

        "dst\_filepath": "someotherfile"

      }

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "user\_id": 123,

  "src\_siteid": 12,

  "dst\_siteid": 14,

  "src\_filepath": "somefile",

  "dst\_filepath": "someotherfile",

  "type": "COPY",

  "status": "SUBMITTED",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

`POST` `/remove`[¶](#post--remove "Permalink to this definition")

Register a remove job.

| Request JSON Object: |

| --- |

|  | * **src\_siteid** (*int*) – source site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts (optional)

* **priority** (*int*) – the job’s priority 0-9 (optional default: 5)

* **protocol** (*int/string*) – the protocol to use for the job (optional default: [`GRIDFTP`](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP"))

 |

| Response JSON Object: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

 |

**Example request**:

```

POST /workqueue/api/v1.0/remove HTTP/1.1

Host: example.com

Accept: application/json

Data: {

        "src\_siteid": 12,

        "src\_filepath": "somefile"

      }

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "user\_id": 123,

  "src\_siteid": 12,

  "src\_filepath": "somefile",

  "type": "REMOVE",

  "status": "SUBMITTED",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

`POST` `/rename`[¶](#post--rename "Permalink to this definition")

Register a rename job.

| Request JSON Object: |

| --- |

|  | * **src\_siteid** (*int*) – source site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the source filesystem

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts (optional)

* **priority** (*int*) – the job’s priority 0-9 (optional default: 5)

* **protocol** (*int/string*) – the protocol to use for the job (optional default: [`GRIDFTP`](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP"))

 |

| Response JSON Object: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

* [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

 |

**Example request**:

```

POST /workqueue/api/v1.0/rename HTTP/1.1

Host: example.com

Accept: application/json

Data: {

        "src\_siteid": 12,

        "src\_filepath": "somefile",

        "dst\_filepath": "someotherfile"

      }

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "user\_id": 123,

  "src\_siteid": 12,

  "dst\_siteid": 12,

  "src\_filepath": "somefile",

  "dst\_filepath": "someotherfile",

  "type": "RENAME",

  "status": "SUBMITTED",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

`POST` `/mkdir`[¶](#post--mkdir "Permalink to this definition")

Register a mkdir job.

| Request JSON Object: |

| --- |

|  | * **src\_siteid** (*int*) – source site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts (optional)

* **priority** (*int*) – the job’s priority 0-9 (optional default: 5)

* **protocol** (*int/string*) – the protocol to use for the job (optional default: [`GRIDFTP`](#pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP "pdm.workqueue.WorkqueueDB.JobProtocol.GRIDFTP"))

 |

| Response JSON Object: |

|  | * **id** (*int*) – job id

* **user\_id** (*int*) – user’s id

* **src\_siteid** (*int*) – source site’s id

* **dst\_siteid** (*int*) – destination site’s id

* **src\_filepath** (*string*) – the path to the file/dir on the source filesystem

* **dst\_filepath** (*string*) – the desired path to the file/dir on the destination filesystem

* **type** (*string*) – the job’s type (see [`pdm.workqueue.WorkqueueDB.JobType`](#pdm.workqueue.WorkqueueDB.JobType "pdm.workqueue.WorkqueueDB.JobType"))

* **status** (*string*) – the job’s status (see [`pdm.workqueue.WorkqueueDB.JobStatus`](#pdm.workqueue.WorkqueueDB.JobStatus "pdm.workqueue.WorkqueueDB.JobStatus"))

* **extra\_opts** (*object*) – any additional options passed on to the command execution scripts

* **priority** (*int*) – the job’s priority 0-9

* **protocol** (*string*) – the protocol to use for the job (see [`pdm.workqueue.WorkqueueDB.JobProtocol`](#pdm.workqueue.WorkqueueDB.JobProtocol "pdm.workqueue.WorkqueueDB.JobProtocol"))

* **log\_uid** (*string*) – a unique hash string where the job’s logs will be kept

* **timestamp** (*string*) – iso-formatted timestamp of last change in DB

 |

| Status Codes: | * [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

* [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) – no error

* [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) – client error with input data

* [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) – unexpected server error either creating job or registering it in DB

 |

**Example request**:

```

POST /workqueue/api/v1.0/mkdir HTTP/1.1

Host: example.com

Accept: application/json

Data: {

        "src\_siteid": 12,

        "src\_filepath": "~/somedir"

      }

```

**Example response**:

```

HTTP/1.1 200 OK

Content-Type: application/json

{

  "id": 1,

  "user\_id": 123,

  "src\_siteid": 12,

  "src\_filepath": "~/somedir",

  "type": "MKDIR",

  "status": "SUBMITTED",

  "extra\_opts": {},

  "priority": 5,

  "protocol": "GRIDFTP",

  "log\_uid": "somelonghash",

  "timestamp": "2012-03-21T13:35"

}

```

Site Service API[¶](#site-service-api "Permalink to this headline")

-------------------------------------------------------------------

The site service keeps a database of site information and provides site-domain

authentication. All functions require a user token unless otherwise stated. All

certificates are in PEM format unless otherwise stated.

The auth\_type parameter currently accepts two constants:

* 0 - PLAIN\_AUTH, Authentication is done using a vanilla user proxy.

* 1 - VOMS\_AUTH, Authentication expects a VOMS proxy.

If a site has a service CA or user CA, then those are used for all operations.

If both are None, then the CA directory from the config is used. Failing that,

the system level CA certificates will be used to verify connections & users at

the site.

`GET /service`

Return central service information. The output keys are all optional and

will only be included if the server is configured to support the relevant

feature.

Requires no authentication.

Returns a dictionary containing:

* central\_ca(str): PEM encoded CA certificate(s) for central services.

* user\_ep(str): The full endpoint for the user service.

* vos(list): A list of strings of VO names supported by this service.

`GET /site`

Returns a list of all sites that the current user can see. This will be

all sites owned by them and all public sites.

Returns a list of dictonaries containing:

* site\_id(int): The unique site ID.

* site\_name(str): The (unique) short site name.

* site\_desc(str): The longer site description.

* def\_path(str): The default (starting) path to use at this site.

* public(bool): Set to true if this site is visible to everyone.

* is\_owner(bool): Set to true if the user is the owner of the site.

`GET /site/<site_id(int)>`

Gets information on a specific site. Only works on sites which the user

can see (as owner or public), other sites will return 404 even if they exist.

Returns a dictionary containing:

* site\_id(int): The unique site ID.

* site\_name(str): The site name.

* site\_desc(str): The longer site description.

* user\_ca\_cert(str): The CA used for user certificates (or None).

* service\_ca\_cert(str): The CA used for site services (or None).

* auth\_type(int): The authentication mode for this site.

* auth\_uri(str): The myproxy endpoint for this site in host:port format.

* public(bool): If true, site is visible to all users.

* def\_path(str): The default path to use when connecting to this site.

* is\_owner(bool): Set to true if the current user owns this site.

* endpoints(list of str): List of gridftp endpoints for this site in

host:port format.

`POST /site`

Register a new site.

Input (POST dictionary):

Same as get site, but without is\_owner. user\_ca\_cert and service\_ca\_cert

are optional and can be ommitted or set to None if unneeded.

Returns (int):

The site\_id of the registered/updated site.

`DELETE /site/<site_id(int)>`

Deletes a site. A user can only delete sites that they are the owner of.

Returns:

* None.

`GET /endpoint/<site_id(int)>`

Get a list of endpoints for a given site. Generally configured for

certificate authentication.

Returns dict with keys:

* endpoints - List of str, gridftp endpoints host:port format.

* cas - (Optional) List of str, PEM encoded CAs for this endpoint.

`DELETE /user/<user_id(int)>`

Deletes all data about the given user ID. A user may only delete themselves.

This removes all sites and cached credentials belonging to the user.

`GET /session/<site_id(int)>`

Gets the sessions information for the current user at the given site.

Optional return paramters may be missing from the dict entriely.

Returns (dictionary):

* ok(bool): Set to True if there is a valid credential.

* username(str, optional): The username for the user at this site.

* expiry(str-datetime, optional): The expiry time of the credential if one

is registered (may be in the past).

`POST /session/<site_id(int)>`

Login a user at the given site. If a user is already logged on, their

credential will be renewed/replaced by the new one if successful.

Input (POST dictionary):

* username(str): The site-specific username.

* password(str): The users’ site password.

* lifetime(int): The time (in hours) to create the credential for.

* voms(str, optional): The VO to use in the credential VOMS extension.

Returns:

* None

`DELETE /session/<site_id(int)>`

Logs a user out from a site. If the user doesn’t have a session

then nothing happens and success is still returned.

Returns:

* None.

`GET /cred/<site_id(int)>/<user_id(int)>`

Get the user credential for a given site and central user ID.

Authentication is ususally done by cert. Returns 404 if user

doesn’t have a credential for the given site.

Returns:

* PEM encoded proxy for the user.

Indices and tables[¶](#indices-and-tables "Permalink to this headline")

=======================================================================

* [Index](genindex.html)

* [Module Index](py-modindex.html)

* [Search Page](search.html)

### Related Topics

* [Documentation overview](index.html#document-index)

### Quick search

 ©2018, Imperial College, HEP Group.

 

 |

 Powered by [Sphinx 1.8.5](http://sphinx-doc.org/)

 & [Alabaster 0.7.12](https://github.com/bitprophet/alabaster)

