Skip to content

Commit 16ee3b0

Browse files
author
github-actions
committed
Auto-update from Github Actions Workflow
Deployed from commit 0828548 (refs/tags/v1.22.0) Deployed from commit 0828548 (refs/tags/v1.22.0)
1 parent d4a35c0 commit 16ee3b0

File tree

203 files changed

+29975
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

203 files changed

+29975
-3
lines changed

‎index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
<!DOCTYPE html>
22
<html>
33
<head>
4-
<meta http-equiv="Refresh" content="0; url=v1.21.0" />
4+
<meta http-equiv="Refresh" content="0; url=v1.22.0" />
55
</head>
66
<body>
7-
<p>Go to the <a href="v1.21.0">default documentation</a>.</p>
7+
<p>Go to the <a href="v1.22.0">default documentation</a>.</p>
88
</body>
99
</html>

‎v1.22.0/_sources/beamline.rst.txt‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Beamline File
2+
=============
3+
4+
Each hutch repository has an ``xxx/beamline.py`` file that is pointed to in
5+
the ``conf.yml`` file. This is intended to be a place for hutches to create
6+
hutch-specific objects or startup changes and additions. You are encouraged
7+
to port your hutch-specific classes upstream and add the objects to the
8+
database, but this is not necessary in every case.
9+
10+
The import rules for this file can be thought of as the most basic:
11+
12+
.. code-block:: python
13+
14+
from xxx.beamline import *
15+
16+
17+
This means we'll include everything in the module, unless an ``__all__`` list is
18+
found to specify the behavior of a ``*`` import.
19+
20+
As specified on the `yaml_files` page, ``conf.yml`` can be extended to import
21+
from multiple modules:
22+
23+
.. code-block:: YAML
24+
25+
load:
26+
- xxx.beamline
27+
- xxx.my_module

‎v1.22.0/_sources/bug.rst.txt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
bug.py
2+
======
3+
.. automodule:: hutch_python.bug
4+
5+
.. autosummary::
6+
:toctree: generated
7+
:nosignatures:
8+
9+
hutch_python.bug.get_current_environment
10+
hutch_python.bug.get_last_n_commands
11+
hutch_python.bug.get_text_from_editor
12+
hutch_python.bug.report_bug
13+
hutch_python.bug.post_to_github

‎v1.22.0/_sources/cache.rst.txt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
cache.py
2+
========
3+
4+
.. automodule:: hutch_python.cache
5+
6+
.. autoclass:: LoadCache
7+
:members:
8+
:special-members: __call__

‎v1.22.0/_sources/cli.rst.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
cli.py
2+
======
3+
4+
.. automodule:: hutch_python.cli

‎v1.22.0/_sources/daq.rst.txt‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
DAQ
2+
===
3+
4+
The following objects are provided for interacting with the data acquisition
5+
system:
6+
7+
- ``daq``: controls execution of the run
8+
- ``scan_pvs``: controls the auxilliary scan pvs, which are used to
9+
organize the run tables.
10+
11+
Full documentation is available at `<https://pcdshub.github.io/pcdsdaq>`_.
12+
This page will be a brief overview.
13+
14+
.. note::
15+
16+
``scan_pvs`` are disabled by default! This is to prevent confusion from
17+
two users accidentally writing to the PVs at the same time. Call
18+
``scan_pvs.enable()`` to enable them. You may consider doing this as part
19+
of your standard scan routine.
20+
21+
22+
Basic Usage
23+
-----------
24+
25+
Use ``daq.begin`` to start a run. Runs must be ended explicitly or the
26+
run will remain open. A second call to a begin during an open run will
27+
resume the run.
28+
29+
.. ipython:: python
30+
:suppress:
31+
32+
from bluesky.run_engine import RunEngine
33+
from bluesky.plans import scan
34+
from ophyd.sim import motor
35+
from pcdsdaq.daq import Daq
36+
from pcdsdaq.sim import set_sim_mode
37+
38+
set_sim_mode(True)
39+
RE = RunEngine({})
40+
daq = Daq(RE=RE)
41+
42+
.. ipython:: python
43+
44+
# Run for 120 events, wait, leave the run open.
45+
daq.begin(events=120, wait=True)
46+
# Close the run
47+
daq.end_run()
48+
# Run for 1 second, record, set the run to end automatically
49+
daq.begin(duration=1, record=True, end_run=True)
50+
# Wait until done taking data
51+
daq.wait()
52+
53+
The python will steal control from the GUI. Only one or the other can have
54+
control at a time. Use ``daq.disconnect`` to give up control to the GUI.
55+
56+
.. ipython:: python
57+
58+
daq.disconnect()
59+
60+
You can start an infinite run using ``daq.begin_infinite``. You can stop this
61+
run manually using ``daq.end_run``.
62+
63+
64+
In a Scan
65+
---------
66+
67+
Use the ``daq`` object as your detector to include it in a ``bluesky`` plan.
68+
The ``DAQ`` will then run for the configured duration at every scan step.
69+
If ``scan_pvs`` are enabled, these will be written to during the ``bluesky``
70+
plan.
71+
72+
.. ipython:: python
73+
74+
# Configure for 120 events per point
75+
daq.preconfig(events=120)
76+
# Scan motor from 0 to 10 in 11 steps, run daq at each point
77+
RE(scan([daq], motor, 0, 10, 11))
78+
79+
80+
Controlling Post-Scan State
81+
---------------------------
82+
83+
The daq will return to the state it was in before the scan was run. If we
84+
start disconnected, we will revert to disconnected. If we start configured,
85+
we will stay connected and configured. If we start while already running,
86+
we'll start running again (``record=False``) after the scan.
87+
88+
The ``daq.configure`` method must connect, so the ``daq.preconfig``
89+
method is provided if you'd like to schedule a configuration to apply
90+
upon connecting in the scan.

‎v1.22.0/_sources/database.rst.txt‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
Database Objects
2+
================
3+
4+
Database objects are objects that are loaded from the shared device database.
5+
This has the advantage of allowing us to have consistent devices across
6+
different hutches and it reduces clutter in the `beamline <beamline>` file.
7+
8+
After loading a ``hutch-python`` session, a file is created at ``xxx/db.txt``
9+
detailing every device that was loaded, in the order they were loaded.
10+
This file has no function, but it serves as rough guide for understanding
11+
which objects the database is providing.
12+
13+
All database objects can be found in a special module called ``xxx.db`` that
14+
is created at runtime. This will work like a normal module you can import
15+
from:
16+
17+
.. code-block:: python
18+
19+
from bluesky.plans import scan
20+
from mfx.db import RE, mfx_attenuator
21+
22+
RE(scan([], mfx_attenuator, 0, 1, 10))
23+
24+
25+
This can be used to bring database or `beamline <beamline>` objects into the
26+
`experiment <experiment>` file.

‎v1.22.0/_sources/debug.rst.txt‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
Debug
2+
=====
3+
4+
There are numerous debug features built in to ``hutch-python``.
5+
6+
Live Session Logging
7+
--------------------
8+
9+
The first place to go when something has already gone wrong is to the log
10+
files. These are stored in a ``logs`` directory in the same location as the
11+
``conf.yml`` file, and sorted by date and session start time.
12+
13+
These contain every log message from the session in the order they were called.
14+
Each module can choose when to make calls to ``logger.debug`` to generate
15+
log messages, but we also log every single input line, output line, and
16+
exception that was raised in the interactive session. Note that the input and
17+
output lines are not available to the logger until the entire command has
18+
executed, so the log messages immediately preceding an input log are those
19+
that were created by calling that statement.
20+
21+
The logging configuration is specified by the ``logging.yaml`` file and is
22+
set up by the :py:mod:`log_setup` module. If not in debug mode, only log levels
23+
``INFO`` and above will make it to the terminal. The files are configured to
24+
rotate and roll over into a second file once they get too large.
25+
26+
27+
Default Log Filtering Rules
28+
---------------------------
29+
The following filtering rules are applied to the console logs:
30+
31+
- Loggers and ophyd object logging adapters that send many messages in a short
32+
period of time will stop being logged. This can be configured using the
33+
``logs.filter`` object.
34+
- Calls to ``warnings.warn`` will be redirected to the ``logging`` module
35+
stream at "WARNING" level, and duplicate messages will be dropped to "DEBUG"
36+
level for the console. This is similar to how warnings behave normally
37+
outside of IPython sessions, but this way we also get a record of them in
38+
the normal log file.
39+
- Subscription callback exceptions from ophyd objects will be demoted from
40+
"ERROR" level to "DEBUG" level to prevent spam while preserving error
41+
logs.
42+
- All log messages from ophyd objects at "INFO" level will also be demoted to
43+
"DEBUG" level to prevent spam.
44+
45+
46+
PCDS-wide Logging
47+
-----------------
48+
49+
A special Python logger for PCDS-wide logging is pre-configured within
50+
``hutch-python``. This special logger is named ``'pcds-logging'``, and hooks
51+
in with our managed logstash, ElasticSearch and Grafana stack.
52+
53+
To explore the data, access Grafana `here
54+
<https://pswww.slac.stanford.edu/ctl/grafana/explore>`_.
55+
56+
To record information, first get the logger itself:
57+
58+
.. code-block:: python
59+
60+
import logging
61+
pcds_logger = logging.getLogger('pcds-logging')
62+
63+
64+
Log messages above the configured level (by default ``logging.DEBUG``) will be
65+
transmitted to the centralized log server to be recorded and indexed.
66+
67+
One example use case is when an important event that would be useful to see
68+
trended over time:
69+
70+
.. code-block:: python
71+
72+
pcds_logger.info('I dropped the sample')
73+
74+
75+
Or for exception statistics, perhaps. The following will include a full stack
76+
trace along with module and line information automatically:
77+
78+
79+
try:
80+
1/0
81+
except ZeroDivisionError:
82+
pcds_logger.exception('This specific thing went wrong')
83+
84+
85+
It is not necessary to include information about the host that is running
86+
Python, module versions, or thread/process names as these are automatically
87+
included.
88+
89+
90+
Debug Mode and Logging Tools
91+
----------------------------
92+
93+
You can start in debug mode by passing the ``--debug`` option to
94+
``hutch-python``. Debug mode changes the logging configuration to print
95+
log messages of level ``DEBUG`` and above to the screen. If that's a bit much,
96+
or if you change your mind during a session, we have a ``logs`` namespace
97+
with all of the relevant logging configuration tooling.
98+
99+
- `logs.log_objects <hutch_python.log_setup.log_objects>`
100+
Used to configure ``DEBUG`` level logging for specific devices.
101+
- `logs.log_objects_off <hutch_python.log_setup.log_objects_off>`
102+
Used to reset previous calls to ``log_objects``.
103+
- `logs.get_log_directory <hutch_python.log_setup.get_log_directory>`
104+
Returns the current configured log path.
105+
- `logs.get_session_logfiles <hutch_python.log_setup.get_session_logfiles>`
106+
Returns a list of all the logfiles generated by this session.
107+
- `logs.get_console_level_name <hutch_python.log_setup.get_console_level_name>`
108+
Returns the name of the console's log level, e.g. "INFO"
109+
- `logs.set_console_level <hutch_python.log_setup.set_console_level>`
110+
Change the log level of the console logging handler.
111+
- `logs.debug_mode <hutch_python.log_setup.debug_mode>`:
112+
A shortcut for setting the console level between "INFO" and "DEBUG".
113+
- `logs.debug_context <hutch_python.log_setup.debug_context>`:
114+
Context manager for enabling debug mode for a block of code.
115+
- `logs.filter <hutch_python.log_setup.ObjectFilter>`:
116+
Get the ophyd object filter that's on the console handler.
117+
This contains a whitelist for allowing spammy loggers and a blacklist
118+
for hiding non-spammy loggers.
119+
- `logs.file_filter <hutch_python.log_setup.ObjectFilter>`:
120+
The same as above, but for the file handler.
121+
122+
123+
.. code-block:: python
124+
125+
logs.debug_mode(True) # Turn on debug mode
126+
logs.debug_mode(False) # Turn off debug mode
127+
print(logs.debug_mode()) # Check debug mode
128+
129+
# Turn on debug mode for the duration of a code block
130+
with logs.debug_context():
131+
buggy_function(arg)
132+
133+
134+
Automated Test Logging
135+
----------------------
136+
137+
If you're running the automated test suite, each test run is stored in a
138+
module-level ``logs`` folder. This can be useful for diagnosing why the tests
139+
are failing.

‎v1.22.0/_sources/environment.rst.txt‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
Environments
2+
============
3+
4+
Central Install
5+
---------------
6+
7+
Each hutch repository is hard-coded to use the central ``conda`` installs.
8+
You can change this in your developer checkout by editing the ``xxxversion``
9+
file. Take care not to commit changes to this file except to update the central
10+
install version.
11+
12+
For ``python=3.6``, the central install is at ``/reg/g/pcds/pyps/conda/py36``.
13+
It is managed using the `pcds-envs <https://github.com/pcdshub/pcds-envs>`_
14+
module.
15+
16+
You can activate the base environment by calling
17+
``source /reg/g/pcds/pyps/conda/py36env.sh``.
18+
This will give you the latest, you can pick an older environment with
19+
``source /reg/g/pcds/pyps/conda/py36env.sh $ENVNAME``. If you take latest and
20+
run ``conda env list``, you'll see all of the options.
21+
22+
Personal Install
23+
----------------
24+
25+
You may wish to install ``hutch-python`` into your own environment for
26+
development purposes. This can be achieved trivially if your environment is in
27+
`conda <https://conda.io/docs>`_. If your environment is not in conda, I
28+
highly suggest downloading `miniconda <https://conda.io/miniconda.html>`_
29+
and giving it a try.
30+
31+
To pick up all dependencies, run this command:
32+
33+
``conda install hutch-python -c pcds-tag -c defaults -c conda-forge``

0 commit comments

Comments
 (0)