item module

Functions that provide info on a queried ScienceBase item. This module is mostly intended for advanced developers implementing low-level ScienceBase API calls.

Function

Description

url

Returns a ScienceBase item’s URL

sbjson

Returns the sbJSON metadata for a ScienceBase item

browse

Opens a ScienceBase item in a web browser
pwfdf_api.item.url(id, *, fields=None, decode=False, json=False)

Returns a ScienceBase item’s URL

Item URL
url(id)
url(..., *, decode=True)

Returns a ScienceBase item’s catalog URL. By default, returns a percent-encoded URL suitable for web requests. Set decode=True to return a decoded URL, which is more human-readable.

sbJSON URL
url(..., *, json=True)
url(..., *, json=True, fields)

By default, returns a URL for the ScienceBase user interface. Set json=True to return the URL for an sbJSON API query instead. Use the fields input to return a URL used to query specific sbJSON fields.

Inputs:

  • id (str) – A ScienceBase item ID

  • decode (bool) – True to return a decoded URL. False (default) to return a percent-encoded URL suitable for web requests.

  • json (bool) – True to return a URL for a sbJSON API response. False (default) to return a URL for the ScienceBase user interface

  • fields (list[str]) – A list of sbJSON fields that should be queried

Outputs:

str – The ScienceBase item’s url

pwfdf_api.item.sbjson(id, *, fields=None, timeout=15, session=None)

Returns the sbJSON metadata for a ScienceBase catalog item

Item sbJSON
sbjson(id)
sbjson(..., *, fields)

Queries the indicated ScienceBase item and returns the sbJSON response as a dict. Use the fields option to only query specific sbJSON fields.

Advanced Web Request
sbjson(..., *, timeout)
sbjson(..., *, session)

Advanced options for implementing the web request. Use timeout to specify a maximum time in seconds for connecting to the ScienceBase server (default is 15 seconds). This option is typically a scalar, but may also use a vector with two elements. In this case, the first value is the timeout to connect with the server, and the second value is the time for the server to return the first byte. You can also set timeout to None, in which case server queries will never time out. This may be useful for some slow connections, but is generally not recommended as your code may hang indefinitely if the server fails to respond.

Use session option to provide a pre-instantiated requests.Session object for querying the ScienceBase API. If not provided, the command creates (and then closes) a new Session for the request. If you provide a Session object as input, then the session is used to implement the query, but is not closed afterwards. This can be useful when calling pwfdf_api multiple times, as the Session object will preserve the underlying TCP connection, which can improve performance.

Inputs:

  • id (str) – A ScienceBase item ID

  • fields (list[str]) – A list of sbJSON fields that should be queried

  • timeout (float | (float, float) | None) – The maximum number of seconds to connect with the ScienceBase server

  • session (requests.Session) – A pre-existing requests.Session object that should be used to query the ScienceBase API

Outputs:

dict – The sbJSON metadata for the item

pwfdf_api.item.browse(id, *, json=False, fields=None, new=0, autoraise=True)

Opens a ScienceBase catalog item in a web browser

Open Item
browse(id)

Opens the ScienceBase catalog item in a web browser. Returns a boolean indicating whether the page was successfully opened.

Open sbJSON
browse(..., *, json=True)
browse(..., *, json=True, fields)

By default, opens the item in the ScienceBase user interface. Set json=True to open a sbJSON API response instead. Use the fields option to open a query for specific sbJSON fields.

Browser Options
browse(..., *, new)
browse(..., *, autoraise=False)

Web browser options. The new input controls how the page is opened. 0 opens in the current window, 1 opens a new window, and 2 opens a new tab. Set autoraise=False to disable raising the opened page when possible.

Note

Many web browsers ignore both these options.

Inputs:

  • id (str) – A ScienceBase item ID

  • json (bool) – True to open the page for an sbJSON API response. False (default) to open the PWFDF parent in the ScienceBase user interface

  • fields (list[str]) – A list of sbJSON fields that should be queried

  • new (0 | 1 | 2) – (0 - default) current window, (1) new window, (2) new tab

  • autoraise (bool) – True (default) to autoraise the page. False to not autoraise

Outputs:

bool – True if the page was opened successfully. Otherwise False.