Common Support

Core components

Structures are defined here provide some consistency in how common terms are named within this project. (For common terms, such as starting date & time, the server uses different names depending on which interface is in use.)

Here, date & time are represented as datetime.datetime objects, including time zone.

Attributes

DM_APS_DB_WEB_SERVICE_URL

APS Data Management web service URL.

Classes

Esaf(raw, run)	Experiment Safety Assessment Form scheduling details.
ProposalBase(raw, run)	Base class for a single beam time request (proposal).
ScheduleInterfaceBase()	Base class for interface to any scheduling system.
User(raw)	A single user on a proposal (beamtime request).

Functions

is_xsd_workstation()	Is this workstation on the APS network?
iso2dt(isodate)	Convert a text ISO8601 date into a datetime object.
miner(root, path[, default])	Return a value from a nested dictionary-like structure.
printColumns(items[, numColumns, width])	Print a list of items in column order.
table_list(db[, width, replace])	Render a list of dict (with identical keys) as a table.
trim(text[, length])	Return a string that is no longer than length.

apsbss.core.DM_APS_DB_WEB_SERVICE_URL = 'https://xraydtn01.xray.aps.anl.gov:11236'

APS Data Management web service URL.

Tip

APS CAT members may need to define the DM_APS_DB_WEB_SERVICE_URL environment variable based on their sector number. Choose from this table:

sector	DM_APS_DB_WEB_SERVICE_URL
odd number	https://catdtn01.xray.aps.anl.gov:11236
even number	https://catdtn02.xray.aps.anl.gov:11236

class apsbss.core.Esaf(raw, run)

Experiment Safety Assessment Form scheduling details.

to_dict()

Return the ESAF content as a dictionary.

Property Methods

_pi	Return first listed principal investigator or user.
_users	Return a list of all users, as 'User' objects.
description	Return the ESAF description.
endDate	Return the ending date&time of this ESAF.
esaf_id	Return ESAF identifier.
lastNames	List the last names of all users on this proposal.
pi	Return the full name and email of the principal investigator.
sector	Return the sector of this ESAF.
startDate	Return the starting date&time of this ESAF.
status	Return the ESAF approval status.
title	Return the ESAF title.
users	Return a list of the names of all experimenters.

property badges: list

List the badges of all users on this ESAF.

property description: str

Return the ESAF description.

property endDate: datetime

Return the ending date&time of this ESAF.

property esaf_id: int

Return ESAF identifier.

property lastNames: list

List the last names of all users on this proposal.

property pi: str

Return the full name and email of the principal investigator.

property sector: str

Return the sector of this ESAF.

property startDate: datetime

Return the starting date&time of this ESAF.

property status: str

Return the ESAF approval status.

property title: str

Return the ESAF title.

to_dict() → dict

Return the ESAF content as a dictionary.

property users: list

Return a list of the names of all experimenters.

class apsbss.core.ProposalBase(raw, run)

Base class for a single beam time request (proposal).

Override any of the methods to access the raw data from the server.

to_dict()

Return the proposal content as a dictionary.

Property Methods

badges	List the badges of all users on this proposal.
current	Is this proposal scheduled now?
emails	Return a list of the names of all experimenters.
endDate	Return the ending date&time of this proposal.
info	Details provided with this proposal.
lastNames	List the last names of all users on this proposal.
mail_in	Is this a mail-in proposal?
pi	Return the full name and email of the principal investigator.
proposal_id	Return the proposal number.
proprietary	Is this a proprietary proposal?
startDate	Return the starting date&time of this proposal.
title	Return the proposal title.
users	Return a list of the names of all experimenters.

property badges: list

List the badges of all users on this proposal.

property current: bool

Is this proposal scheduled now?

property emails: list

Return a list of the names of all experimenters.

property endDate: datetime

Return the ending date&time of this proposal.

property info: dict

Details provided with this proposal.

property lastNames: list

List the last names of all users on this proposal.

property mail_in: bool

Is this a mail-in proposal?

property pi: str

Return the full name and email of the principal investigator.

property proposal_id: int

Return the proposal number.

property proprietary: bool

Is this a proprietary proposal?

property startDate: datetime

Return the starting date&time of this proposal.

property submittedDate: datetime

Return the submitted date of this proposal.

property title: int

Return the proposal title.

to_dict() → dict

Return the proposal content as a dictionary.

property users: list

Return a list of the names of all experimenters.

class apsbss.core.Run(raw)

Details about an APS run (cycle).

Property Methods

startDate	Return the starting date&time of this run.
endDate	Return the ending date&time of this run.

property endDate: datetime

Return the ending date&time of this run.

property run_id: int

Run identifier, if provided from server, or None.

property startDate: datetime

Return the starting date&time of this run.

class apsbss.core.ScheduleInterfaceBase

Base class for interface to any scheduling system.

Override any of the methods to access the raw data from the server.

getProposal(proposal_id, beamline, run)

Get 'proposal_id' for 'beamline' during 'run'.

Property Methods

beamlines	List of all known beamlines, by name.
current_run	All details about the current run.
proposals(beamline[, run])	Get all proposal (beamtime request) details for 'beamline' and 'run'.
_runs	Details (from server) about all known runs.
runs	List of names of all known runs.

abstract property beamlines: list

List of all known beamlines, by name.

property current_run: dict

All details about the current run.

getProposal(proposal_id, beamline, run)

Get ‘proposal_id’ for ‘beamline’ during ‘run’. None if not found.

abstract proposals(beamline: str, run: str = None) → dict

Get all proposal (beamtime request) details for ‘beamline’ and ‘run’.

Credentials must match to the specific beamline.

Parameters

beamlinestr

beamline ID as stored in the APS scheduling system, e.g. 2-BM-A,B or 7-BM-B or 32-ID-B,C

runstr

Run name e.g. ‘2024-1’. Default: name of the current run.

Returns

proposalsdict

Dictionary of ‘ProposalBase’ objects, keyed by proposal ID (str), scheduled on ‘beamline’ for ‘run’.

property runs: list

List of names of all known runs.

class apsbss.core.User(raw)

A single user on a proposal (beamtime request).

Property Methods

affiliation	Name of affiliation (institution).
badge	ANL badge number
email	Email address
firstName	Given name.
fullName	firstName lastName
lastName	Family name.
is_pi	Is this user the principal investigator?
user_id	ID of the user.
institution	Name of the user's institution.
institution_id	ID of the user's institution.

property affiliation

Name of affiliation (institution).

property badge: str

ANL badge number

property email: str

Email address

property firstName: str

Given name.

property fullName: str

firstName lastName

property institution: str

Name of the user’s institution.

property institution_id: int

ID of the user’s institution.

property is_pi: bool

Is this user the principal investigator?

property lastName: str

Family name.

property user_id: int

ID of the user.

apsbss.core.is_xsd_workstation()

Is this workstation on the APS network?

apsbss.core.iso2dt(isodate) → datetime

Convert a text ISO8601 date into a datetime object.

PARAMETERS

isodatestr

Date and time in modified ISO8601 format. (e.g.: 2020-07-01 12:34:56.789012) Fractional seconds are optional.

apsbss.core.miner(root, path: str, default=None)

Return a value from a nested dictionary-like structure.

rootdict-like

The nested dictionary-like structure.

path: str

Text description of the keys to be navigated. Keys are separated by dots.

defaultobject

Return this value if ‘path’ is not found. Default is ‘None.

apsbss.core.printColumns(items, numColumns=5, width=10)

Print a list of items in column order.

PARAMETERS

items[str]

List of items to report

numColumnsint

number of columns, optional (default: 5)

widthint

width of each column, optional (default: 10)

apsbss.core.table_list(db, width=40, replace=' ...')

Render a list of dict (with identical keys) as a table.

apsbss.core.trim(text, length=40)

Return a string that is no longer than length.

If a string is longer than length, it is shortened to the length-3 characters, then, ... is appended. For very short length, the string is shortened to length (and no ... is appended).

PARAMETERS

text

str : String, potentially longer than length

length

int : maximum length, optional (default: 40)