Metadata-Version: 2.1
Name: whatrecord
Version: 0.5.0
Summary: EPICS IOC record search and meta information tool
Author: SLAC National Accelerator Laboratory
License: Copyright (c) 2023, The Board of Trustees of the Leland Stanford Junior
        University, through SLAC National Accelerator Laboratory (subject to receipt
        of any required approvals from the U.S. Dept. of Energy). All rights reserved.
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        (1) Redistributions of source code must retain the above copyright notice,
            this list of conditions and the following disclaimer.
        
        (2) Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
        
        (3) Neither the name of the Leland Stanford Junior University, SLAC National
            Accelerator Laboratory, U.S. Dept. of Energy nor the names of its
            contributors may be used to endorse or promote products derived from this
            software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER, THE UNITED STATES GOVERNMENT,
        OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
        EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
        OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
        IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
        OF SUCH DAMAGE.
        
        You are under no obligation whatsoever to provide any bug fixes, patches, or
        upgrades to the features, functionality or performance of the source code
        ("Enhancements") to anyone; however, if you choose to make your Enhancements
        available either publicly, or directly to SLAC National Accelerator Laboratory,
        without imposing a separate written license agreement for such Enhancements,
        then you hereby grant the following license: a non-exclusive, royalty-free
        perpetual license to install, use, modify, prepare derivative works, incorporate
        into other computer software, distribute, and sublicense such Enhancements or
        derivative works thereof, in binary and source code form.
        
        
        ******************************************************************************
        ******************************************************************************
        Portions of this were borrowed/reimplemented/ported from epics-base itself,
        its license is included below.
        ******************************************************************************
        ******************************************************************************
        
        
        Copyright (c) 1991-2011 UChicago Argonne LLC.
        Copyright (c) 1991-2006 The Regents of the University of California.
        Copyright (c) 2006-2011. Los Alamos National Security, LLC. Some of this
        material was produced under U.S. Government contract DE-AC52-06NA25396
        for Los Alamos National Laboratory (LANL), which is operated by Los Alamos
        National Security, LLC for the U.S. Department of Energy.
        
        EPICS BASE is distributed subject to the following license conditions:
        
         SOFTWARE LICENSE AGREEMENT
         Software: EPICS BASE
        
         1. The "Software", below, refers to EPICS BASE (in either source code, or
            binary form and accompanying documentation). Each licensee is
            addressed as "you" or "Licensee."
        
         2. The copyright holders shown above and their third-party licensors
            hereby grant Licensee a royalty-free nonexclusive license, subject to
            the limitations stated herein and U.S. Government license rights.
        
         3. You may modify and make a copy or copies of the Software for use
            within your organization, if you meet the following conditions:
              a. Copies in source code must include the copyright notice and this
                 Software License Agreement.
              b. Copies in binary form must include the copyright notice and this
                 Software License Agreement in the documentation and/or other
                 materials provided with the copy.
        
         4. You may modify a copy or copies of the Software or any portion of it,
            thus forming a work based on the Software, and distribute copies of
            such work outside your organization, if you meet all of the following
            conditions:
              a. Copies in source code must include the copyright notice and this
                 Software License Agreement;
              b. Copies in binary form must include the copyright notice and this
                 Software License Agreement in the documentation and/or other
                 materials provided with the copy;
              c. Modified copies and works based on the Software must carry
                 prominent notices stating that you changed specified portions of
                 the Software.
        
         5. Portions of the Software resulted from work developed under a U.S.
            Government contract and are subject to the following license: the
            Government is granted for itself and others acting on its behalf a
            paid-up, nonexclusive, irrevocable worldwide license in this computer
            software to reproduce, prepare derivative works, and perform publicly
            and display publicly.
        
         6. WARRANTY DISCLAIMER. THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY
            OF ANY KIND. THE COPYRIGHT HOLDERS, THEIR THIRD PARTY LICENSORS, THE
            UNITED STATES, THE UNITED STATES DEPARTMENT OF ENERGY, AND THEIR
            EMPLOYEES: (1) DISCLAIM ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
            BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS
            FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, (2) DO NOT ASSUME
            ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS,
            OR USEFULNESS OF THE SOFTWARE, (3) DO NOT REPRESENT THAT USE OF THE
            SOFTWARE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS, (4) DO NOT WARRANT
            THAT THE SOFTWARE WILL FUNCTION UNINTERRUPTED, THAT IT IS ERROR-FREE
            OR THAT ANY ERRORS WILL BE CORRECTED.
        
         7. LIMITATION OF LIABILITY. IN NO EVENT WILL THE COPYRIGHT HOLDERS, THEIR
            THIRD PARTY LICENSORS, THE UNITED STATES, THE UNITED STATES DEPARTMENT
            OF ENERGY, OR THEIR EMPLOYEES: BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
            CONSEQUENTIAL, SPECIAL OR PUNITIVE DAMAGES OF ANY KIND OR NATURE,
            INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR LOSS OF DATA, FOR ANY
            REASON WHATSOEVER, WHETHER SUCH LIABILITY IS ASSERTED ON THE BASIS OF
            CONTRACT, TORT (INCLUDING NEGLIGENCE OR STRICT LIABILITY), OR
            OTHERWISE, EVEN IF ANY OF SAID PARTIES HAS BEEN WARNED OF THE
            POSSIBILITY OF SUCH LOSS OR DAMAGES.
        
        ________________________________________________________________________
        
        This software is in part copyrighted by the BERLINER SPEICHERRING
        GESELLSCHAFT FUER SYNCHROTRONSTRAHLUNG M.B.H. (BESSY), BERLIN, GERMANY.
        
        In no event shall BESSY be liable to any party for direct, indirect,
        special, incidental, or consequential damages arising out of the use of
        this software, its documentation, or any derivatives thereof, even if
        BESSY has been advised of the possibility of such damage.
        
        BESSY specifically disclaims any warranties, including, but not limited
        to, the implied warranties of merchantability, fitness for a particular
        purpose, and non-infringement.  This software is provided on an "as is"
        basis, and BESSY has no obligation to provide maintenance, support,
        updates, enhancements, or modifications.
        ________________________________________________________________________
        
Classifier: Development Status :: 5 - Production/Stable
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE.md
License-File: AUTHORS.rst
Requires-Dist: aiohttp
Requires-Dist: apischema[graphql]
Requires-Dist: epicsmacrolib
Requires-Dist: graphviz<0.18
Requires-Dist: jinja2
Requires-Dist: lark
Provides-Extra: test
Requires-Dist: codecov; extra == "test"
Requires-Dist: flake8; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: blark; extra == "test"
Requires-Dist: happi; extra == "test"
Requires-Dist: python-ldap; extra == "test"
Requires-Dist: pytmc; extra == "test"
Provides-Extra: doc
Requires-Dist: mkdocs; extra == "doc"
Requires-Dist: mkdocs-autorefs; extra == "doc"
Requires-Dist: mkdocs-material; extra == "doc"
Requires-Dist: mkdocstrings[python]; extra == "doc"
Requires-Dist: pytkdocs[numpy-style]; extra == "doc"

===============================
whatrecord
===============================

.. image:: https://img.shields.io/travis/pcdshub/whatrecord.svg
        :target: https://travis-ci.org/pcdshub/whatrecord

.. image:: https://img.shields.io/pypi/v/whatrecord.svg
        :target: https://pypi.python.org/pypi/whatrecord


EPICS IOC record search and meta information tool.

Spiritual successor of recordwhat.

https://pcdshub.github.io/whatrecord/

What?
-----

Lark grammar-based parsers which parse any of the following into easy-to-use
Python dataclasses:

* EPICS access security files (.acf)
* EPICS autosave save files (.sav)
* EPICS V3 database files
* EPICS V4 database files
* EPICS msi-style template/substitutions files (.template/.substitutions)
* EPICS gateway configuration (.pvlist)
* EPICS sequencer state notation language programs (.st)
* EPICS StreamDevice protocols (.proto)

All of the above can be easily serialized to JSON for interoperability.

Pseudo-IOC shell interpreter:

* Reads st.cmd files as if it were an IOC
* Loads and lints record files (and other supported formats above)
* Builds inter- and intra- IOC PV relationship graphs
* Stores context information about where each record/field/etc came from

API server

* IOC finder (LCLS IOC manager, list of files, or external script)
* Provides access to all parsed information above
* Preliminary asyncio-based client to talk with the server

Frontend

* User-friendly vue.js v3 frontend that communicates with API server
* Interfaces for:
    - Searching for records
    - Record relationships (processing and links, cross-IOC links)
    - IOC information
    - Gateway configuration overview
    - Duplicate records
    - Optional plugins

Plugins

* happi devices
* Simple LDAP search (LCLS hosts, "netconfig")
* LCLS-specific epicsArch / logbook DAQ PVs
* TwinCAT PLC source code (pytmc)

Makefile / build system information

* Determine build dependencies from a ``Makefile``
* Recursively inspect sub-dependencies
* Graph IOC dependency information or output it as JSON

Command-line tools

* ``whatrecord lint`` - lint a database
* ``whatrecord parse`` - parse supported formats
* ``whatrecord server`` - start the API server
* ``whatrecord graph`` - graph PV relationships, SNL diagrams, IOC dependencies

Record?
-------

https://docs.epics-controls.org/en/latest/guides/EPICS_Process_Database_Concepts.html#the-epics-process-database

Requirements
------------

Requirements:

* Python 3.9
* aiohttp
* apischema[graphql]
* graphviz
* jinja2
* lark

Docker
------

See `/docker </docker>`_ to set up a Python 3.10-based whatrecord container.
A docker-compose configuration for starting up the frontend/backend servers
is also provided.  Note that the default configuration only indexes the
whatrecord-provided IOCs.

Frontend Screenshots
--------------------

Search for records and view relationships:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_1.png

View StreamDevice protocol information:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_2.png

See where your qsrv pvAccess keys come from:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_3.png

See access security settings:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_4.png

View all of your IOCs in one place and browse their records by type:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_5.png

View inter-IOC record relationships:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_6.png

View all of your ophyd/happi devices and their relevant PVs:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_7.png

View LDAP-provided settings:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_8.png

(LCLS-specific) View epicsArch DAQ PVs:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_9.png

View gateway PVList configurations:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_10.png

View record duplicates:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_11.png

View API server logs:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_12.png

See per-parameter values:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_13.png
.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_15.png

See database lint:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_14.png


Other Screenshots
-----------------

Use ``whatrecord deps --graph`` to inspect IOCs/modules with ``make`` and
generate a dependency graph of modules:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_16.png

Use ``whatrecord graph`` to graph state notation language ``.st`` file
logic:

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_17.png

.. image:: https://github.com/pcdshub/whatrecord/raw/assets/screenshot_18.png

Use an external tool like ``jq`` to sift through information from whatrecord's
JSON output:

.. code::

  $ whatrecord parse whatrecord/tests/iocs/db/pva/iq.db | jq '.records[] | [.name, .record_type, .fields.OUT.value]'
  [
    "$(PREFIX)Rate",
    "ao",
    "$(PREFIX)dly_.ODLY NPP"
  ]
  [
    "$(PREFIX)Delta",
    "ao",
    null
  ]
  ...

  $ whatrecord parse whatrecord/tests/iocs/db/pva/iq.db | jq '.records[] | [ .name, .info["Q:group"]]'
  [
    "$(PREFIX)Rate",
    null
  ]
  [
    "$(PREFIX)Phase:I",
    {
      "$(PREFIX)iq": {
        "phas.i": {
          "+type": "plain",
          "+channel": "VAL"
        }
      }
    }
  ]
  ...
