diff --git a/pr-preview/pr-12/404.html b/pr-preview/pr-12/404.html new file mode 100644 index 0000000..0caf02c --- /dev/null +++ b/pr-preview/pr-12/404.html @@ -0,0 +1,253 @@ + + + +
+ + + + + + + + + + + + + + +dts: a Python client for the Data Transfer Service.
+The Data Transfer System (DTS) offers a federated +search capability for participating organizations in the DOE Biological and +Environmental Research program, and allows the transfer of related data and +metadata between these organizations.
+DTS API documentation is available here.
+ + + + + + + + +Client
+
+
+dts.Client
: A client for performing file transfers with the Data Transfer System (DTS).
This type exposes the DTS API for use +in Python programs.
+ + + + + + +dts/client.py
30 + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 + 59 + 60 + 61 + 62 + 63 + 64 + 65 + 66 + 67 + 68 + 69 + 70 + 71 + 72 + 73 + 74 + 75 + 76 + 77 + 78 + 79 + 80 + 81 + 82 + 83 + 84 + 85 + 86 + 87 + 88 + 89 + 90 + 91 + 92 + 93 + 94 + 95 + 96 + 97 + 98 + 99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 |
|
__init__(api_key=None, server=None, port=None)
+
+Creates a DTS client that handles search and transfer requests via +a connected server.
+If no server is specified, you must call connect
on the created client.
Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ api_key
+ |
+
+ str | None
+ |
+
+
+
+ An unencoded KBase developer token. + |
+
+ None
+ |
+
+ server
+ |
+
+ str | None
+ |
+
+
+
+ The DTS server that handles the client's API requests. + |
+
+ None
+ |
+
+ port
+ |
+
+ int | None
+ |
+
+
+
+ The port to which the client connects with the server. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ None
+ |
+
+
+
+ a |
+
Raises:
+Type | +Description | +
---|---|
+ TypeError
+ |
+
+
+
+ an argument of improper type was specified. + |
+
dts/client.py
36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 |
|
cancel_transfer(id)
+
+Cancels a file transfer with the requested UUID.
+Status information for the cancelled transfer is retained for a time so its +cancellation can be seen.
+ + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ id
+ |
+
+ UUID
+ |
+
+
+
+ A UUID that uniquely identifies the transfer operation to be cancelled. + |
+ + required + | +
Raises:
+Type | +Description | +
---|---|
+ RuntimeError
+ |
+
+
+
+ Indicates an issue with the DTS client and its connection to the server. + |
+
+ TypeError
+ |
+
+
+
+ Indicates that an argument passed to the client isn't of the proper type. + |
+
+ ValueError
+ |
+
+
+
+ Indicates that an argument passed to the client has an invalid value. + |
+
dts/client.py
376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 |
|
connect(api_key=None, server=None, port=None)
+
+Connects the client to the given DTS server via the given port using the given +(unencoded) KBase developer token.
+ + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ api_key
+ |
+
+ str | None
+ |
+
+
+
+ An unencoded KBase developer token. + |
+
+ None
+ |
+
+ server
+ |
+
+ str | None
+ |
+
+
+
+ The DTS server that handles the client's API requests. + |
+
+ None
+ |
+
+ port
+ |
+
+ int | None
+ |
+
+
+
+ The port to which the client connects with the server. + |
+
+ None
+ |
+
Raises:
+Type | +Description | +
---|---|
+ TypeError
+ |
+
+
+
+ an argument of improper type was specified. + |
+
+ ConnectionError
+ |
+
+
+
+ the client was unable to connect to the DTS server. + |
+
dts/client.py
63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 |
|
databases()
+
+Returns all databases available to the service.
+Server-side errors are captured and logged.
+ + +Returns:
+Type | +Description | +
---|---|
+ list[Database]
+ |
+
+
+
+ A list of Database objects containing information about available databases. + |
+
dts/client.py
106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 |
|
disconnect()
+
+Disconnects the client from the server.
+ +dts/client.py
98 + 99 +100 +101 +102 +103 +104 |
|
fetch_metadata(database, ids, offset=0, limit=None)
+
+Fetches metadata for the files with the specified IDs within the specified database.
+Server-side errors are intercepted and logged.
+ + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ database
+ |
+
+ str
+ |
+
+
+
+ A string containing the name of the database to search. + |
+ + required + | +
+ ids
+ |
+
+ list[str]
+ |
+
+
+
+ A list containing file identifiers for which metadata is retrieved. + |
+ + required + | +
+ offset
+ |
+
+ int
+ |
+
+
+
+ An optional 0-based pagination index from which to start retrieving results (default: 0). + |
+
+ 0
+ |
+
+ limit
+ |
+
+ int | None
+ |
+
+
+
+ An optional pagination parameter indicating the maximum number of results to retrieve. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ list[JsonResource]
+ |
+
+
+
+ A list of frictionless DataResources containing metadata for files with the requested IDs. + |
+
Raises:
+Type | +Description | +
---|---|
+ RuntimeError
+ |
+
+
+
+ Indicates an issue with the DTS client and its connection to the server. + |
+
+ TypeError
+ |
+
+
+
+ Indicates that an argument passed to the client isn't of the proper type. + |
+
+ ValueError
+ |
+
+
+
+ Indicates that an argument passed to the client has an invalid value. + |
+
dts/client.py
206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 |
|
search(database, query, status=None, offset=0, limit=None, specific=None)
+
+Performs a synchronous search of the database with the given name using the given query string.
+This method searches the indicated database for files that can be transferred.
+ + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ database
+ |
+
+ str
+ |
+
+
+
+ A string containing the name of the database to search. + |
+ + required + | +
+ query
+ |
+
+ str | int | float
+ |
+
+
+
+ A search string that is directly interpreted by the database. + |
+ + required + | +
+ status
+ |
+
+ str | None
+ |
+
+
+
+ An optional string ( |
+
+ None
+ |
+
+ offset
+ |
+
+ int
+ |
+
+
+
+ An optional 0-based pagination index indicating the first retrieved result (default: 0). + |
+
+ 0
+ |
+
+ limit
+ |
+
+ int | None
+ |
+
+
+
+ An optional pagination parameter indicating the maximum number of results to retrieve. + |
+
+ None
+ |
+
+ specific
+ |
+
+ dict[str, Any] | None
+ |
+
+
+
+ An optional dictionary mapping database-specific search parameters to their values. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ list[JsonResource]
+ |
+
+
+
+ A list of frictionless DataResources containing metadata for files matching the query. + |
+
Raises:
+Type | +Description | +
---|---|
+ RuntimeError
+ |
+
+
+
+ Indicates an issue with the DTS client and its connection to the server. + |
+
+ TypeError
+ |
+
+
+
+ Indicates that an argument passed to the client isn't of the proper type. + |
+
+ ValueError
+ |
+
+
+
+ Indicates that an argument passed to the client has an invalid value. + |
+
dts/client.py
131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 |
|
transfer(file_ids, source, destination, description=None, instructions=None, timeout=None)
+
+Submits a request to transfer files from a source to a destination database.
+Server-side errors are intercepted and logged.
+ + +Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ file_ids
+ |
+
+ list[str]
+ |
+
+
+
+ A list of identifiers for files to be transferred. + |
+ + required + | +
+ source
+ |
+
+ str
+ |
+
+
+
+ The name of the database from which files are transferred. + |
+ + required + | +
+ destination
+ |
+
+ str
+ |
+
+
+
+ The name of the database to which files are transferred. + |
+ + required + | +
+ description
+ |
+
+ str | None
+ |
+
+
+
+ An optional string containing human-readable Markdown text describing the transfer. + |
+
+ None
+ |
+
+ instructions
+ |
+
+ dict[str, Any] | None
+ |
+
+
+
+ An optional dict representing a JSON object containing instructions for processing the payload at its destination. + |
+
+ None
+ |
+
+ timeout
+ |
+
+ int | None
+ |
+
+
+
+ An optional integer indicating the number of seconds to wait for a response from the server. + |
+
+ None
+ |
+
Returns:
+Type | +Description | +
---|---|
+ UUID | None
+ |
+
+
+
+ A UUID uniquely identifying the file transfer that can be used to check its status, or None if a server-side error is encountered. + |
+
Raises:
+Type | +Description | +
---|---|
+ RuntimeError
+ |
+
+
+
+ Indicates an issue with the DTS client and its connection to the server. + |
+
+ TypeError
+ |
+
+
+
+ Indicates that an argument passed to the client isn't of the proper type. + |
+
+ ValueError
+ |
+
+
+
+ Indicates that an argument passed to the client has an invalid value. + |
+
dts/client.py
264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 |
|
transfer_status(id)
+
+Returns status information for the transfer with the given identifier.
+Server-side errors are intercepted and logged. Possible transfer statuses are:
+'staging'
: The files requested for transfer are being copied to the staging
+ area for the source database job.'active'
: The files are being transferred from the source database to the
+ destination database.'finalizing'
: The files have been transferred and a manifest is being written.'inactive'
: The file transfer has been suspended.'failed'
: The file transfer could not be completed because of a failure.'unknown'
: The status of the given transfer is unknown.Parameters:
+Name | +Type | +Description | +Default | +
---|---|---|---|
+ id
+ |
+
+ UUID
+ |
+
+
+
+ A UUID that uniquely identifies the transfer operation for which the status is requested. + |
+ + required + | +
Returns:
+Type | +Description | +
---|---|
+ TransferStatus | None
+ |
+
+
+
+ A |
+
Raises:
+Type | +Description | +
---|---|
+ RuntimeError
+ |
+
+
+
+ Indicates an issue with the DTS client and its connection to the server. + |
+
+ TypeError
+ |
+
+
+
+ Indicates that an argument passed to the client isn't of the proper type. + |
+
+ ValueError
+ |
+
+
+
+ Indicates that an argument passed to the client has an invalid value. + |
+
dts/client.py
328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 |
|
Database
+
+
+
+ dataclass
+
+
+Database
- A database storing files that can be selected and transferred.
This type holds human-readable information about databases available to DTS. +Objects of this type are returned by calls to the DTS API, so it is not +necessary to construct them directly.
+ + + + + + +dts/database.py
3 + 4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 |
|
TransferStatus
+
+
+
+ dataclass
+
+
+TransferStatus
status information for a file transfer.
This type holds information pertaining to the transfer of a payload initiated +via the DTS. Objects of this type are returned by calls to the DTS API, so it +is not necessary to create them directly.
+ + + + + + +dts/transfer_status.py
4 + 5 + 6 + 7 + 8 + 9 +10 +11 +12 +13 +14 +15 +16 |
|