Utilities

Various utilities

connect_pvlist(pvlist[, wait, timeout, …]) given a list of EPICS PV names, return a dictionary of EpicsSignal objects
EmailNotifications([sender]) send email notifications when requested
ExcelDatabaseFileBase() base class: read-only support for Excel files, treat them like databases
ExcelDatabaseFileGeneric(filename[, labels_row]) Generic (read-only) handling of Excel spreadsheet-as-database
ipython_profile_name() return the name of the current ipython profile or None
print_snapshot_list(db, **search_criteria) print (stdout) a list of all snapshots in the databroker
text_encode(source) encode source using the default codepoint
to_unicode_or_bust(obj[, encoding]) from: http://farmdev.com/talks/unicode/
unix_cmd(command_list) run a UNIX command, returns (stdout, stderr)
class APS_BlueSky_tools.utils.EmailNotifications(sender=None)[source]

send email notifications when requested

use default OS mail utility (so no credentials needed)

send(subject, message)[source]

send message to all addresses

class APS_BlueSky_tools.utils.ExcelDatabaseFileBase[source]

base class: read-only support for Excel files, treat them like databases

EXAMPLE

Show how to read an Excel file where one of the columns contains a unique key. This allows for random access to each row of data by use of the key.

class ExhibitorsDB(ExcelDatabaseFileBase):
    '''
    content for Exhibitors, vendors, and Sponsors from the Excel file
    '''
    EXCEL_FILE = os.path.join("resources", "exhibitors.xlsx")
    LABELS_ROW = 2

    def handle_single_entry(self, entry):
        '''any special handling for a row from the Excel file'''
        pass

    def handleExcelRowEntry(self, entry):
        '''identify the unique key for this entry (row of the Excel file)'''
        key = entry["Name"]
        self.db[key] = entry
class APS_BlueSky_tools.utils.ExcelDatabaseFileGeneric(filename, labels_row=3)[source]

Generic (read-only) handling of Excel spreadsheet-as-database

Table labels are given on Excel row N, self.labels_row = N-1

handleExcelRowEntry(entry)[source]

use row number as the unique key

APS_BlueSky_tools.utils.connect_pvlist(pvlist, wait=True, timeout=2, poll_interval=0.1)[source]

given a list of EPICS PV names, return a dictionary of EpicsSignal objects

PARAMETERS

pvlist : list(str)
list of EPICS PV names
wait : bool
should wait for EpicsSignal objects to connect, default: True
timeout : float
maximum time to wait for PV connections, seconds, default: 2.0
poll_interval : float
time to sleep between checks for PV connections, seconds, default: 0.1
APS_BlueSky_tools.utils.ipython_profile_name()[source]

return the name of the current ipython profile or None

Example (add to default RunEngine metadata):

RE.md['ipython_profile'] = str(ipython_profile_name())
print("using profile: " + RE.md['ipython_profile'])
APS_BlueSky_tools.utils.print_snapshot_list(db, **search_criteria)[source]

print (stdout) a list of all snapshots in the databroker

USAGE:

print_snapshot_list(db, )
print_snapshot_list(db, purpose="this is an example")
print_snapshot_list(db, since="2018-12-21", until="2019")

EXAMPLE:

In [16]: from APS_BlueSky_tools.utils import print_snapshot_list
    ...: from APS_BlueSky_tools.callbacks import SnapshotReport 
    ...: print_snapshot_list(db, since="2018-12-21", until="2019") 
    ...:                                                                                                                            
= ======== ========================== ==================
# uid      date/time                  purpose           
= ======== ========================== ==================
0 d7831dae 2018-12-21 11:39:52.956904 this is an example
1 5049029d 2018-12-21 11:39:30.062463 this is an example
2 588e0149 2018-12-21 11:38:43.153055 this is an example
= ======== ========================== ==================

In [17]: SnapshotReport().print_report(db["5049029d"])

========================================
snapshot: 2018-12-21 11:39:30.062463
========================================

example: example 2
hints: {}
iso8601: 2018-12-21 11:39:30.062463
look: can snapshot text and arrays too
note: no commas in metadata
plan_description: archive snapshot of ophyd Signals (usually EPICS PVs)
plan_name: snapshot
plan_type: generator
purpose: this is an example
scan_id: 1
software_versions: {
    'python': 
        '''3.6.2 |Continuum Analytics, Inc.| (default, Jul 20 2017, 13:51:32)
        [GCC 4.4.7 20120313 (Red Hat 4.4.7-1)]''', 
    'PyEpics': '3.3.1', 
    'bluesky': '1.4.1', 
    'ophyd': '1.3.0', 
    'databroker': '0.11.3', 
    'APS_Bluesky_Tools': '0.0.38'
    }
time: 1545413970.063167
uid: 5049029d-075c-453c-96d2-55431273852b

========================== ====== ================ ===================
timestamp                  source name             value              
========================== ====== ================ ===================
2018-12-20 18:24:34.220028 PV     compress         [0.1, 0.2, 0.3]    
2018-12-13 14:49:53.121188 PV     gov:HOSTNAME     otz.aps.anl.gov    
2018-12-21 11:39:24.268148 PV     gov:IOC_CPU_LOAD 0.22522317161410768
2018-12-21 11:39:24.268151 PV     gov:SYS_CPU_LOAD 9.109026666525944  
2018-12-21 11:39:30.017643 PV     gov:iso8601      2018-12-21T11:39:30
2018-12-13 14:49:53.135016 PV     otz:HOSTNAME     otz.aps.anl.gov    
2018-12-21 11:39:27.705304 PV     otz:IOC_CPU_LOAD 0.1251210270549924 
2018-12-21 11:39:27.705301 PV     otz:SYS_CPU_LOAD 11.611234438304471 
2018-12-21 11:39:30.030321 PV     otz:iso8601      2018-12-21T11:39:30
========================== ====== ================ ===================

exit_status: success
num_events: {'primary': 1}
run_start: 5049029d-075c-453c-96d2-55431273852b
time: 1545413970.102147
uid: 6c1b2100-1ef6-404d-943e-405da9ada882
APS_BlueSky_tools.utils.text_encode(source)[source]

encode source using the default codepoint

APS_BlueSky_tools.utils.to_unicode_or_bust(obj, encoding='utf-8')[source]

from: http://farmdev.com/talks/unicode/

APS_BlueSky_tools.utils.unix_cmd(command_list)[source]

run a UNIX command, returns (stdout, stderr)