2. Getting Started

2.1. File and FileSystem usage

2.1.1. Synchronous and Asynchronous requests

The new XRootD client is capable of making both synchronous and asynchronous requests. Therefore, pyxrootd must also be capable of this, although most people will probably only need synchronous functionality most of the time.

Each method in the File and FileSystem classes can take an optional callback argument. If you don’t pass in a callback, you’re asking for a synchronous request. If you do, the request becomes asynchronous (assuming the callback is valid, of course), and your callback will be invoked when the response is received.

pyxrootd comes with a callback helper class: XRootD.client.utils.AsyncResponseHandler. If you use an instance of this class as your callback, you can call the wait() function whenever you like after the request is made, and it will block until the response is received.

2.1.2. Return types


The return signature of the File and FileSystem functions changes depending on whether you make a synchronous or asynchronous request, so be careful. Synchronous requests

You always get a 2-tuple in return when you make a synchronous request. The first item in the tuple is always an XRootD.client.responses.XRootDStatus instance. The XRootDStatus object tells you whether the request was successful or not, along with some other information.

The second item in the tuple depends on which request you made. If it’s a simple request without any response information, such as XRootD.client.FileSystem.ping(), the second item is None. Otherwise, you get one of the objects in XRootD.client.responses. For example, if you call XRootD.client.FileSystem.dirlist(), you get an instance of XRootD.client.responses.DirectoryList. Asynchronous requests

You get a single object, an XRootD.client.responses.XRootDStatus instance, when you fire off an asynchronous request. This can inform you about any immediate problems in making the request, e.g. the network is not reachable (or something).

However, when that callback you gave us (remember him?) gets triggered - you get not 2, but a 3-tuple. The first, again, is an XRootDStatus. The second follows the synchronous pattern, i.e. you get your response object, or None. The third item is an XRootD.client.responses.HostList instance. This contains a list of all the hosts that were implicated while carrying out that request you made.

2.1.3. Timeouts

All of the functions in this class accept an optional timeout keyword argument. The default timeout is 0, which means that the environment default will be used. You can change the timeout value on a per-request basis with the optional parameter, or you can set it system-wide with the XRD_REQUESTTIMEOUT environment variable. Also, the timeout resolution (time interval between timeout detection) can be set with the XRD_TIMEOUTRESOLUTION environment variable.

2.2. Copying files

If you want to copy files simply and quickly with default options, you can just use XRootD.client.FileSystem.copy().

But if you want more configurable copy jobs, or you want to copy a large number of files at once, you can use XRootD.client.CopyProcess.

You can even pass in a copy progress handler to CopyProcess.run() and use it to build some kind of progress display (much like the xrdcopy command does).