SDpyshell
=========
Introduction
------------
The StructuredData python shell (SDpyshell) provides a simple way to query,
modify, export and import StructuredData.
The SDpyshell can be started without arguments, you then get a command prompt
where you can enter commands interactively.
It can be started with the "-c" option, where you provide all commands as
parameter for the "-c" option.
It can be started with the "-s" option followed by a number, in this case the
shell runs in *server mode*. Now the user can connect to the shell with "telnet
[hostname] [port]" and issue commands on the telnet prompt.
It can be started as a script interpreter with the well known shebang syntax.
Just put this at the first line of your file::
#!/usr/bin/env SDpyshell
It will then interpret the rest of the file as SDpyshell commands.
Basic Syntax
------------
SDpyshell has the same syntax as the python (version 2) language. It works like the interactive python interpreter with some extra functions, classes and objects. You can load python modules with the `import` statement and use them in the shell.
For details on python syntax look at
`Python 2.7 documentation `_.
function calls
++++++++++++++
A function call is a name followed by a list of arguments enclosed in round
brackets. All the arguments are separated by commas `,`.
Here are examples for simple function calls, one with unnamed and one with
named parameters. Named parameters are followed by a "=" and a value::
myfunction(arg1, arg2, arg3)
myfunction(arg1, name2=value2, name3=value3)
Two functions can be called in a single line when they are separated by a
semicolon::
myfunction1(arg1, arg2); myfunction2(arg3, arg4)
You may spread spread arguments to functions across several lines like
that::
myfunction(arg1, arg2,
arg3, arg4)
You may have expressions as a value to a function. The following calls
myfunction with 1 and 5::
myfunction(1, 2+3)
The brackets decide what the function parameters are. In the following line,
myfunction is called with 1 and 2, the results of myfunction is then added to
3::
myfunction(1, 2) + 3
Parameter values may also be function calls::
myfunction(1, myfunction2(3 4))
procedure calls
+++++++++++++++
Procedures are functions that get no arguments. A name on a single line
followed by an opening and closing round bracket is interpreted as a procedure
call. Note that the brackets must not be omitted, here is an example::
myprocedure()
More than one procedure call in a line have to be separated with a semicolon::
myprocedure1(); myprocedure2()
string literals
+++++++++++++++
All python string literals are allowed. Simple examples are::
"a string"
'a string'
"""a string across
several lines"""
.. _SDpyshell-basic-function:
Basic function
--------------
The SDpyshell has a global variable "fun.SDC" which is initially an empty
StructuredDataContainer. All operations work with this variable unless the
parameter "sdc" is set to a value different from fun.SDC.
It is important to know that consecutive read operations *add* data to the
StructuredDataContainer. The old data *is not* deleted when new data is read,
both are merged. If the new data has different values for items already present
in the StructuredDataContainer, they are overwritten with the new values.
.. _SDpyshell-command-layers:
Command layers
--------------
A command is either a *function* or a *procedure*. Both may alter the
StructuredData but functions always return a value where procedures don't. We
call commands that print results to the console but don't return a value
procedures.
There are three layers of commands in SDpyshell:
**functional layer**
These are functions that return simple data or data structures. The data
returned usually is not a simple string. These functions are used to *write
programs*. Functions that belong to this category start with "fun." like in
"fun.get".
**text layer**
These are functions that always return a string that may contain several
lines of text. The functions in this category are used to *capture* the text
that the commands in the following category would print to the console.
Functions that belong to that category start with "txt." like in "txt.get".
**interactive layer**
Commands in this category are intended to be used in the interactive shell.
They never return values but may print messages or results of queries to the
console. These commands *do not* have a leading "fun." or "txt." in their
name like in "get".
Format Specifications
---------------------
Many commands in SDpyshell allow the user to specify the format of the data
returned. Not all commands support all formats, for details see the
`Commands and Functions`_.
The format is usually specified as a string that consists of format keywords
separated by colon characters. Here is an example::
"yaml:py:flat"
The following sections list all known format keywords.
Structure Formats
+++++++++++++++++
These format keywords specify the kind of structure that is read from or
written to the file. Only one of these keywords may be part of a format
specification string.
container
This specifies that a StructuredDataContainer is used.
store
This specifies that a StructuredDataStore is used.
types
This specifies that a StructuredDataTypes structure is used.
Text formats
++++++++++++
These format keywords specify the way the data is represented as text. Only one
of these keywords may be part of a format specification string.
"yaml"
This stands for the YAML format. Some functions can read or write in this
format.
"py"
This stands for the python format. Data in this format is fully compatible
with python data declarations.
"csv"
This stands for "comma separated value". Only a StructuredDataStore can be
written in this format. It cannot be used to read a file.
"raw"
This stands for "raw python". The value is printed to the console with the
python "print" command. This format is only available in function "get".
"aligned"
This is a format where paths are followed by values where all values are
aligned. This format is only available in functions "find", "ifind", "rxfind",
"findval", "ifindval" and "rxfindval".
Marking links
+++++++++++++
"marklinks"
Commands that print paths allow to mark the places in paths that refer to
data that is referenced in at least one other place. A mark is a star "\*"
appended to the end of a key. In "a.b*.c" for example, "a.b" is a link, this
data is referenced somewhere else in the StructuredDataStore.
"hidelinks"
With this format keyword, links are not marked.
Flat format
+++++++++++
These are format keywords that are used together with `Text formats`_.
"flat"
This format can be used for writing a StructuredDataStore. In this case the
command writes path-value pairs instead of a hierarchical structure.
"nonflat"
This is the usual hierarchical format.
Dry run
+++++++
These format keywords are used at some commands to indicate that the command
should not take any action but only show what it would do.
"run"
This format keyword specifies regular command execution. It is only here to
have an opposite to "dry-run".
"dry-run"
This format keyword specifies that the command only shows what it *would* do.
.. _SDpyshell-commands:
Commands and Functions
----------------------
The following text is basically the same the "help" command shows for each
command.
Generic functions
+++++++++++++++++
help
####
help()
::::::
This command for interactive use displays help for a given help topic or
command. If no arguments are given it displays all help topics.
The command takes the following parameters:
- *item*: This specifies the help topic which must be a string. This
parameter is optional. If it is not provided or *None* the command
displays a list of all help topics.
- *level*: This specifies the help level. This parameter is mandatory if a
help topic with the same name occurs at more than one place in the list of
help topics. It is then used to specify exactly which help topic is
requested. If you request a topic that is more than once in the list, the
help command shows you all topics together with their level parameter.
.. _SDpyshell-txt_help:
txt.help()
::::::::::
This command returns the text that `help()`_ prints to the console as a string.
For an explanation of parameters look at the description of `help()`_.
fun.help()
::::::::::
This command is identical to `txt.help()`_.
SDtype
######
fun.SDtype()
::::::::::::
This function returns a string that indicates the type of StructuredData
application currently running. It's main application is to write portable
*extensions* which are python modules that can run in SDpyshell and SDxmlrpc. It
returns one of these strings:
- library: The StructuredData python libraries are called from an unknown
application.
- SDpyshell: The program running is the SDpyshell.
- SDxmlrpc: The program running is SDxmlrpc.
String and path functions
+++++++++++++++++++++++++
.. _SDpyshell-format:
format
######
format()
::::::::
This command for interactive use formats the given value and prints it to the
screen. It takes the follwoing parameters:
- *val*: This is the value to format.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw", "csv", "aligned". "raw" means that the value is simply
printed without enclosing quotes or anything. "aligned" means that keys and
values are column-aligned, this format cannot be applied to all data. Note
that format "csv" does not produce sensible output for some kinds of data.
The default is "yaml".
txt.format()
::::::::::::
This command formats the given value in the way that `format()`_ does but
returns the text instead or printing it. For an explanation of parameters look
at the description of `format()`_.
.. _SDpyshell-string2pathkey:
string2pathkey
##############
string2pathkey()
::::::::::::::::
This command for interactive use converts an arbitrary string to a valid path
key. If the string contains the characters ".[]" a backslash "\\" is prepended
to each character. This is also the case when the string is "\*", "\*\*" or
"#" since these have a special meaning in path patterns. The result in printed
to the screen. For more information on paths see also :ref:`paths
`.
- *st*: This specifies the string to convert.
Here are some examples::
> string2pathkey('abc')
abc
> string2pathkey('a.b.c')
a\\.b\\.c
> string2pathkey('ab[3]')
ab\\[3\\]
> string2pathkey('*')
\\*
> string2pathkey('\\*')
\\\\*
> string2pathkey('#')
\\#
> string2pathkey('\\#')
\\\\#
txt.string2pathkey()
::::::::::::::::::::
This function returns the text that `string2pathkey()`_ prints to the console
as a string. For an explanation of parameters look at the description of
`string2pathkey()`_.
fun.string2pathkey()
::::::::::::::::::::
This function returns the text that `string2pathkey()` prints to the console as
a string. For an explanation of parameters look at the description of
`string2pathkey()`_.
pathkey2string
##############
pathkey2string()
::::::::::::::::
This command for interactive use converts a valid pathkey to a string. If the
pathkey contains the characters ".[]" prepended by a backslash "\\", the
backslash is removed at each position. This is also done if the backslash is
followed by "\*", "\*\*" or "#". For more information on paths see also
:ref:`paths `.
- *pk*: This specifies the pathkey to convert.
Here are some examples::
> pathkey2string('abc')
abc
> pathkey2string('a\\.b\\.c')
a.b.c
> pathkey2string('\\*')
*
> pathkey2string('\\#')
#
txt.pathkey2string()
::::::::::::::::::::
This function returns the text that `pathkey2string()`_ prints to the console
as a string. For an explanation of parameters look at the description of
`pathkey2string()`_.
fun.pathkey2string()
::::::::::::::::::::
This function returns the text that `pathkey2string()`_ prints to the console
as a string. For an explanation of parameters look at the description of
`pathkey2string()`_.
splitpath
#########
splitpath()
:::::::::::
This command for interactive use splits a given path/pattern or a list of
paths/patterns into it's keys. Note that if the pattern contains the wildcards
"\*" or "\*\*" the korrespoding key the symbol *ANYKEY* respective *ANYKEYS*.
These are special gobal variables that represents the wildcard symbols. Note
too that the symbols *ANYKEY* and *ANYKEYS* cannot be printed in YAML format.
The command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". "raw" means that the value is simply printed without
enclosing quotes or anything. The default is "yaml".
Here are some examples::
> splitpath("01_facility[0].description")
- 01_facility
- 0
- description
> splitpath("01_facility[0].description", "py")
['01_facility', 0, 'description']
> splitpath("a.*.b", "py")
['a', ANYKEY, 'b']
txt.splitpath()
:::::::::::::::
This function returns the text that `splitpath()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`splitpath()`_.
Here is an example::
> print txt.splitpath("01_facility[0].description")
- 01_facility
- 0
- description
fun.splitpath()
:::::::::::::::
This command splits a given path or a list of paths into it's keys. It returns
a list of strings and integers. The command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
Here are some examples::
> print fun.splitpath("01_facility[0].description")
['01_facility', 0, 'description']
> print fun.splitpath("01_facility[0].description")[2]
description
joinpath
########
joinpath()
::::::::::
This command for interactive use converts a list of keys to a path. The keys
are either arbitrary strings or the global symbol *ANYKEY* which represents the
"\*" wildcard. The command takes the following parameters:
- *keys*: This is a list of keys. The are joined to form a *path*. See also
:ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw".
"raw" means that the value is simply printed without enclosing quotes or
anything. The default is "raw".
Here are some examples::
> joinpath([:01_facility, 0, :description ])
01_facility[0].description
> joinpath([:01_facility, :0, :description ])
01_facility.0.description
> joinpath([:01_facility, ANYKEY, :description ])
01_facility.*.description
txt.joinpath()
::::::::::::::
This command returns the text that `joinpath()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`joinpath()`_.
Here are some examples::
> print txt.joinpath([:01_facility, 0, :description ])
01_facility[0].description
> print txt.joinpath([:01_facility, :0, :description ])
01_facility.0.description
fun.joinpath()
::::::::::::::
This command converts a list of keys to a path and returns the path as a
string. The command takes the following parameters:
- *keys*: This is a list of keys. The are joined to form a *path*. See also
:ref:`paths `.
Here are some examples::
> print fun.joinpath([:01_facility, 0, :description ])
01_facility[0].description
> get(fun.joinpath([:01_facility, 0, :description ]))
BESSY II Ring
combinepaths
############
combinepaths()
::::::::::::::
This command for interactive use combines a list of paths to a new single path
and returns it as a string. The command takes the following parameters:
- *paths*: This is a list of paths. These are joined to form a new *path*.
See also :ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw".
"raw" means that the value is simply printed without enclosing quotes or
anything. The default is "raw".
Here is an example::
> combinepaths(["AB.CD","EF","GH.IJ"])
AB.CD.EF.GH.IJ
txt.combinepaths()
::::::::::::::::::
This command returns the text that `combinepaths()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`combinepaths()`_.
fun.combinepaths()
::::::::::::::::::
This command converts a list of keys to a path and returns the path as a
string. The command takes the following parameters:
- *paths*: This is a list of paths. The are joined to form a *path*.
See also :ref:`paths `.
Here is an example::
> print fun.combinepaths(["AB.CD","EF","GH.IJ"])
AB.CD.EF.GH.IJ
addpaths
########
addpaths()
::::::::::
This command for interactive use combines two paths or a list of paths with a
second path to a new path or path list. The command takes the following
parameters:
- *path1*: This is the first part of the new path. This parameter may be a
single path or a list of paths.
- *path2*: This is the second part of the new path. This parameter may be a
single path or a list of paths.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw".
"raw" means that the value is simply printed without enclosing quotes or
anything. The default is "raw".
Here are some examples::
> addpaths("ab.cd", "ef.gh")
ab.cd.ef.gh
> addpaths(["ab.cd", "xx.yy"], "ef.gh")
['ab.cd.ef.gh', 'xx.yy.ef.gh']
> addpaths("ab.cd", ["ef.gh", "xx.yy"])
['ab.cd.ef.gh', 'ab.cd.xx.yy']
txt.addpaths()
::::::::::::::
This command returns the text that `addpaths()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`addpaths()`_.
fun.addpaths()
::::::::::::::
This function adds two paths. One of the paths arguments may also be a list of paths, in this case the function returns a new list of paths.
- *path1*: This specifies the first path or a list of paths. See also
:ref:`paths `.
- *path2*: This specifies the second path or a list of paths.
Here are some examples::
> print fun.addpaths("ab.cd", "ef.gh")
ab.cd.ef.gh
> print fun.addpaths(["ab.cd", "xx.yy"], "ef.gh")
['ab.cd.ef.gh', 'xx.yy.ef.gh']
> print fun.addpaths("ab.cd", ["ef.gh", "xx.yy"])
['ab.cd.ef.gh', 'ab.cd.xx.yy']
poppath
#######
poppath()
:::::::::
This command for interactive use removes one or more keys from a path or a list
of paths. It takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". "raw" means that the value is simply printed without
enclosing quotes or anything. The default is "raw".
- *no*: This parameters specifies the number of keys to remove. It's default is
1. If this number is positive, keys are removed *from the end* of the path.
If this number is negative, keys are removed *from the start* of the path.
Here are some examples::
> poppath("01_facility[0].description")
01_facility[0]
> poppath("01_facility[0].description", no=2)
01_facility
> poppath("01_facility[0].description", no=-2)
description
txt.poppath()
:::::::::::::
This command returns the text that `poppath()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`poppath()`_.
fun.poppath()
:::::::::::::
This command removes one or more keys from a path or a list of paths from the
end to the start and returns the new path as a string. It takes the following
parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *no*: This parameters specifies the number of keys to remove. It's default is
1. If this number is positive, keys are removed *from the end* of the path.
If this number is negative, keys are removed *from the start* of the path.
Here are some examples::
> print fun.poppath("01_facility[0].description")
01_facility[0]
> print fun.poppath("01_facility[0].description", no=2)
01_facility
substpath
#########
substpath()
:::::::::::
This command for interactive use changes a path or a list of paths according to
a given pattern. This is a very flexible concept of manipulating paths without
the need to combine several poppath and addpath statements. Each wildcard
("\*") in the pattern is replaced with the matching part of the path.
Non-wildcard parts of the pattern remain unchanged. Please do also have a look
at the examples below. The command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *pattern*: This is a path pattern. See also
:ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". "raw" means that the value is simply printed without
enclosing quotes or anything. The default is "raw".
Here are some examples::
> substpath("a.b.c.d", "*.X.*.*")
a.X.c.d
> substpath("a.b.c.d", "*.X.*.Y")
a.X.c.Y
> substpath("a.b.c.d", "*.*")
a.b
> substpath("a.b.c.d", "*.*.*.*.e.f")
a.b.c.d.e.f
> substpath("a.b.c.d", "*.*.X")
a.b.X
> substpath("a.b[3].d", "*.*[4].*")
a.b[4].d
> substpath(["a.b.c.d", "e.f.g.h" ], "*.X.*.*")
['a.X.c.d', 'e.X.g.h']
txt.substpath()
:::::::::::::::
This command returns the text that `substpath()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`substpath()`_.
.. _SDpyshell-fun.substpath:
fun.substpath()
:::::::::::::::
This command changes a path or a list of paths according to a given pattern.
This is a very flexible concept of manipulating paths without the need to
combine several poppath and addpath statements. Each wildcard ("\*") in the
pattern is replaced with the matching part of the path. Non-wildcard parts of
the pattern remain unchanged. Please do also have a look at the examples of
`substpath()`_. The command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *pattern*: This is a path pattern. See also
:ref:`patterns `.
Functions for the StructuredDataContainer
+++++++++++++++++++++++++++++++++++++++++
newsdc
######
fun.newsdc()
::::::::::::
This command creates a new StructuredDataContainer and returns a handle to it.
For SDpyshell this handle is the StructuredDataContainer object itself. For
SDxmlrpc the handle is a generated string. You need this command if you intend
to use more than one StructuredDataContainer at a time. All procedures for
interactive use use a global StructuredDataContainer if it is not specified
otherwise.
namedsdc
########
fun.namedsdc()
::::::::::::::
This command is similar to fun.newsdc. It creates a new StructuredDataContainer
and returns a handle to it. With this function, the user can provide a handle
as parameter. Note that makes only a difference for SDxmlrpc. For SDpyshell, the
parameter to this function is ignored.
The command takes the following parameters:
- *arg*: The name that is used as a handle to the new StructuredDataContainer.
When used from SDpyshell, this name is ignored and the returned handle is the
StructuredDataContainer object.
locksdc
#######
fun.locksdc()
:::::::::::::
This command locks the given StructuredDataContainer. A locked
StructuredDataContainer may not be modified, trying to modify the object raises
an exception.
The command takes the following parameters:
- *sdc*: The StructuredDataContainer that is to be locked.
copy
####
copy()
::::::
This command for interactive use returns a copy of a StructuredDataContainer.
Note that this is a *deep* copy, the copied object does never change when the
source is changed later on. These are the parameters of this command:
- *sdc*: The source StructuredDataContainer object. If this parameter is
omitted, the command creates a copy from the global variable
":ref:`fun.SDC `".
txt.copy()
::::::::::
This command is identical to `copy()`_.
fun.copy()
::::::::::
This command is identical to `copy()`_.
File I/O
++++++++
lockfile
########
fun.lockfile()
::::::::::::::
This command defines the given file to be read only. Trying to modify this file
raises an exception.
The command takes the following parameters:
- *filename*: The name of the file.
lockdir
#######
fun.lockdir()
:::::::::::::
This command defines the given directory to be read only. Trying to modify this
directory raises an exception.
The command takes the following parameters:
- *dirname*: The name of the directory.
read
####
read()
::::::
This command for interactive use is used to read a StructuredDataContainer, a
StructuredDataStore or StructuredDataTypes from a file. The data read is
usually added to the global variable ":ref:`fun.SDC
`") which is a StructuredDataContainer. The command
prints the names of the files read to the console.
If this command is issued several times, the new data is added to the data that
was already read. The command takes the following parameters:
- *filename*: The name of the file to read. If this parameter is omitted, the
program reads all files named "\*.SDCyml" it finds in the current
directory.
- *formatspec*: The format specification of the file. This is a string of
format keywords separated by colon ":" characters. See
`Format Specifications`_ for details. Allowed format keywords here are:
"container", "store", "types", "yaml", "py", "flat", "nonflat". The default
is "container:yaml:nonflat". - *sdc*: The destination where the new data is
added. If this parameter is omitted, the data is added to the global
StructuredDataContainer ":ref:`fun.SDC `".
This function always returns the StructuredDataContainer where the data was
added.
Here are some examples::
read("myfile")
read("myfile", "py")
read("myfile", "store")
my_sdc= read(filename="myfile", formatspec="store:py", sdc=None)
txt.read()
::::::::::
This command is identical to `read()`_ except that it returns the modified
StructuredDataContainer and a list of the names of the files read.
fun.read()
::::::::::
This command is identical to `read()`_ except that it returns the modified
StructuredDataContainer and a list of the names of the files read.
write
#####
write()
:::::::
The command for interactive use write is used to write the data to a file or
the screen as a StructuredDataContainer, a StructuredDataStore or
StructuredDataTypes. The data written is usually taken from the global variable
":ref:`fun.SDC `") which is a
StructuredDataContainer. If a file was created the command prints the name of
the file created. It takes the following parameters:
- *filename*: The name of the file to write. If this parameter is omitted, the
command prints to the screen.
- *formatspec*: The format specification of the file. This is a string of
format keywords separated by colon ":" characters. See
`Format Specifications`_ for details. Allowed format keywords here are:
"container", "store", "types", "yaml", "py", "csv", "flat", "nonflat". The
default is "container:yaml:nonflat".
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is printed. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
write()
write("myfile," "py")
write(filename="myfile", formatspec="store:flat")
txt.write()
:::::::::::
This command is identical to `write()`_ except that it doesn't print a message
to the console.
fun.write()
:::::::::::
This command is identical to `write()`_ except that it doesn't print a message
to the console.
rewrite
#######
rewrite()
:::::::::
This command for interactive is used to write date that was read from a
StructuredDataContainer, a StructuredDataStore or StructuredDataTypes back to
the file they were read from. Each time the "read" command is called it
remembers the name of the first file it reads together with the format
(container, store or types). When rewrite is called, it uses that stored
filename to write the data to that file. The idea is to read data with the
"read" command, modify it with the SDpyshell and then write it back without
having to enter the filename a second time. The data is usually taken from the
global variable ":ref:`fun.SDC `") which is a
StructuredDataContainer. The command writes the name of the created file to the
console. It takes the following parameters:
- *formatspec*: The format specification of the file. This is a string of
format keywords separated by colon ":" characters. See
`Format Specifications`_ for details. Allowed format keywords here are:
"container", "store", "types", "yaml", "py", "csv", "flat", "nonflat", "run"
and "dry-run". The default is "container:yaml:nonflat:run". When "dry-run" is
given, the command just prints to the screen what file it *would* write to.
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is printed. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
rewrite()
rewrite("dry-run")
Printing
++++++++
pr
##
pr()
::::
This command for interactive is used to print the data as a
StructuredDataContainer, a StructuredDataStore or StructuredDataTypes. The data
printed is usually taken from the global variable ":ref:`fun.SDC
`") which is a StructuredDataContainer. The command
takes the following parameters:
- *formatspec*: The format specification of the file. This is a string of
format keywords separated by colon ":" characters. See
`Format Specifications`_ for details. Allowed format keywords here are:
"container", "store", "types", "yaml", "py", "csv", "flat", "nonflat". The
default is "container:yaml:nonflat".
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is printed. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
pr()
pr("py")
pr(formatspec="store:flat")
Generic functions for the StructuredDataStore
+++++++++++++++++++++++++++++++++++++++++++++
clear_store
###########
clear_store()
:::::::::::::
This command for interactive use empties the StructuredDataStore of a
StructuredDataContainer. If called without parameters, the global
StructuredDataContainer ":ref:`fun.SDC `" is changed.
This command takes the following parameters:
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
txt.clear_store()
:::::::::::::::::
This command is identical to `clear_store()`_.
fun.clear_store()
:::::::::::::::::
This command is identical to `clear_store()`_.
refresh_links
#############
refresh_links()
:::::::::::::::
This command for interactive use refreshes the information on links in the
StructuredDataStore that is cached within the StructuredDataStore. Since this
looks at all paths in the StructuredDataStore it may take some time. However,
if you alter a StructuredDataStore by importing data or apply changes directly
at the objects within the StructuredDataStore and intend to get information on
links, you should issue this command.
txt.refresh_links()
:::::::::::::::::::
This command is identical to `refresh_links()`_.
fun.refresh_links()
:::::::::::::::::::
This command is identical to `refresh_links()`_.
Generic functions for StructuredDataTypes
+++++++++++++++++++++++++++++++++++++++++
clear_types
###########
clear_types()
:::::::::::::
This command for interactive use empties the StructuredDataTypes part of a
StructuredDataContainer. If called without parameters, the global
StructuredDataContainer ":ref:`fun.SDC `" is changed.
This command takes the following parameters:
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
txt.clear_types()
:::::::::::::::::
This command is identical to `clear_types()`_.
fun.clear_types()
:::::::::::::::::
This command is identical to `clear_types()`_.
Querying the data
+++++++++++++++++
paths
#####
paths()
:::::::
The command for interactive use paths is used to print paths found in the
StructuredDataContainer. The data read is usually read from the global
variable ":ref:`fun.SDC `") which is a
StructuredDataContainer. Only paths that match the given pattern are printed.
The command takes the following parameters:
- *pattern*: This specifies the match pattern.
Note that only if your pattern ends with ".**" you get all paths that *start*
with the pattern. If this parameter is omitted it defaults to "*".
See also :ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "raw", "hidelinks", "marklinks". The default is
"yaml:hidelinks".
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> paths()
- id-data
- id-metadata
> paths("id-data.U2.names.*")
- id-data.U2.names.devicename
- id-data.U2.names.key
- id-data.U2.names.name
- id-data.U2.names.prefix
> paths("id-data.U2.names")
- id-data.U2.names
> paths("id-data.U2.names.**")
- id-data.U2.names
- id-data.U2.names.devicename
- id-data.U2.names.key
- id-data.U2.names.name
- id-data.U2.names.prefix
txt.paths()
:::::::::::
This command returns the text that `paths()`_ prints to the console as a
string. For an explanation of parameters look at the description of `paths()`_.
Here is an example::
> print txt.paths("*")
- id-data
- id-metadata
fun.paths()
:::::::::::
The command paths is used to return paths found in the StructuredDataContainer
as a list of strings. The data read is usually read from the global variable
":ref:`fun.SDC `") which is a StructuredDataContainer.
Only paths that match the given pattern are returned. The command takes the
following parameters:
- *pattern*: This specifies the match pattern.
Note that only if your pattern ends with ".**" you get all paths that *start*
with the pattern. If this parameter is omitted it defaults to "*".
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> print fun.paths("*")
['id-data', 'id-metadata']
> print fun.paths("id-data.U2.names")
['id-data.U2.names']
> import pprint
> pprint.pprint(fun.paths("id-data.U2.names", exact_match=False))
['id-data.U2.names',
'id-data.U2.names.devicename',
'id-data.U2.names.key',
'id-data.U2.names.name',
'id-data.U2.names.prefix']
find
####
find()
::::::
This interactive command is used to search the store for a given pattern. It
lists all matching paths together with the data. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is printed. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw", "hidelinks", "marklinks". In aligned
format paths and values are printed separated by a colon ":" where the colons
are aligned in the same column making the output better readable. The default
for this parameter is "aligned:hidelinks".
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> find("id-data.U2.names.**")
id-data.U2.names.devicename: U2IV
id-data.U2.names.key : 98
id-data.U2.names.name : U2
id-data.U2.names.prefix : idcp98
> find("id-data.U2.names.**", "py")
{'id-data.U2.names.devicename': 'U2IV',
'id-data.U2.names.key': 98,
'id-data.U2.names.name': 'U2',
'id-data.U2.names.prefix': 'idcp98'}
> find("id-data.U2.names.**", "csv")
id-data.U2.names.devicename;U2IV
id-data.U2.names.prefix;idcp98
id-data.U2.names.name;U2
id-data.U2.names.key;98
> find("id-data.*.names.key")
id-data.U125/1.names.key : 96
id-data.U125/2.names.key : 3
id-data.U139.names.key : 110
id-data.U2.names.key : 98
id-data.U3.names.key : 97
id-data.U4.names.key : 95
id-data.U41.names.key : 12
id-data.U48.names.key : 80
id-data.U49/1.names.key : 7
id-data.U49/2.names.key : 15
id-data.UE112.names.key : 13
id-data.UE46.names.key : 10
id-data.UE49.names.key : 8
id-data.UE52.names.key : 9
id-data.UE56/1.names.key : 11
id-data.UE56/2.names.key : 5
id-data.UE56R.names.key : 81
id-data.Ubonsai.names.key: 99
txt.find()
::::::::::
This command returns the text that `find()`_ prints to the console as a string.
For an explanation of parameters look at the description of `find()`_.
Here is an example::
> print txt.find("id-data.U2.names.**")
id-data.U2.names.devicename: U2IV
id-data.U2.names.key : 98
id-data.U2.names.name : U2
id-data.U2.names.prefix : idcp98
fun.find()
::::::::::
The function fun.find is used to search the store for a given pattern. It
returns a list of pairs, each pair consisting of a matching path together with
the data. It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is printed. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here is an example::
> pprint.pprint(fun.find("id-data.U2.names.**"))
[('id-data.U2.names.devicename', 'U2IV'),
('id-data.U2.names.prefix', 'idcp98'),
('id-data.U2.names.name', 'U2'),
('id-data.U2.names.key', 98)]
ifind
#####
ifind()
:::::::
This interactive command is similar to the command `find()`_ with the exception
that the pattern is an "i-pattern". An "i-pattern" is a list of space
separated sub-strings. All strings that contain all of these sub-strings in any
order (compared case insensitive) match. This match is applied on all paths of
the StructuredDataContainer. The command usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *pattern*: This specifies the i-pattern.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw", "hidelinks", "marklinks". In aligned
format paths and values are printed separated by a colon ":" where the colons
are aligned in the same column making the output better readable. The default
for this parameter is "aligned:hidelinks".
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> ifind("U2 park")
id-data.U2.referencing.h_park_position: 0
id-data.U2.referencing.v_park_position: 150
> ifind("U2 v park")
id-data.U2.referencing.v_park_position: 150
txt.ifind()
:::::::::::
This command returns the text that `ifind()`_ prints to the console as a
string. For an explanation of parameters look at the description of `ifind()`_.
Here is an example::
> print txt.ifind("U2 v park")
id-data.U2.referencing.v_park_position: 150
fun.ifind()
:::::::::::
The command fun.ifind is similar to the command `find()`_ with the exception
that the pattern is an "i-pattern". An "i-pattern" is a list of space
separated sub-strings. All strings that contain all of these sub-strings in any
order (compared case insensitive) match. This match is applied on all paths of
the StructuredDataContainer. The function returns a list of pairs, each pair
consisting of a matching path together with the data. It usually uses the
global StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *pattern*: This specifies the i-pattern.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
rxfind
######
rxfind()
::::::::
This interactive command is similar to the command find with the exception that
the pattern is a regular expression. This regular expression is matched against
all paths of the StructuredDataContainer. The command usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *regexp*: This specifies the regular expression. See the python documentation
for `regular expression syntax `_.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw", "hidelinks", "marklinks". In aligned
format paths and values are printed separated by a colon ":" where the colons
are aligned in the same column making the output better readable. The default
for this parameter is "aligned:hidelinks".
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> rxfind(r'.*U2.*park')
id-data.U2.referencing.h_park_position: 0
id-data.U2.referencing.v_park_position: 150
> rxfind(r'.*U2.*[vh]_axl')
id-data.U2.interface.h_axle_scheme: 1342
id-data.U2.physical.v_axles : 2
txt.rxfind()
::::::::::::
This command returns the text that `rxfind()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`rxfind()`_.
Here is an example::
> print txt.rxfind(r'.*U2.*park')
id-data.U2.referencing.h_park_position: 0
id-data.U2.referencing.v_park_position: 150
fun.rxfind()
::::::::::::
The command fun.rxfind is similar to the command `fun.find()`_ with the
exception that the pattern is a regular expression. This regular expression is
matched against all paths of the StructuredDataContainer. The function returns
a list of pairs, each pair consisting of a matching path together with the
data. The function usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *regexp*: This specifies the regular expression. See the python documentation
for `regular expression syntax `_.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
findval
#######
findval()
:::::::::
This interactive command is used to search the store for a given value. It
lists all paths together with the values that match the given value. It usually
uses the global StructuredDataContainer ":ref:`fun.SDC
`". The command takes the following parameters:
- *value*: This specifies the value to look for.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw", "hidelinks", "marklinks". In aligned
format paths and values are printed separated by a colon ":" where the colons
are aligned in the same column making the output better readable. The default
for this parameter is "aligned:hidelinks".
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is examined. Note that only if your pattern ends
with ".**" you get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here is an example::
> findval(10)
id-data.U2.config.h_ref_velocity : 10
id-data.U4.config.h_ref_velocity : 10
id-data.U48.config.coil_number : 10
id-data.U48.feedback.cc_tables : 10
id-data.UE112.config.h_ref_velocity : 10
id-data.UE46.global.id-key : 10
id-data.UE46.names.key : 10
id-data.UE49.config.h_ref_velocity : 10
id-metadata.parameter-info.undulator.order_key: 10
> findval(10, pattern="*.*.config.**")
id-data.U2.config.h_ref_velocity : 10
id-data.U4.config.h_ref_velocity : 10
id-data.U48.config.coil_number : 10
id-data.UE112.config.h_ref_velocity: 10
id-data.UE49.config.h_ref_velocity : 10
txt.findval()
:::::::::::::
This command returns the text that `findval()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`findval()`_.
Here is an example::
> print txt.findval(10)
id-data.U2.config.h_ref_velocity : 10
id-data.U4.config.h_ref_velocity : 10
id-data.U48.config.coil_number : 10
id-data.U48.feedback.cc_tables : 10
id-data.UE112.config.h_ref_velocity : 10
id-data.UE46.global.id-key : 10
id-data.UE46.names.key : 10
id-data.UE49.config.h_ref_velocity : 10
id-metadata.parameter-info.undulator.order_key: 10
fun.findval()
:::::::::::::
The command find is used to search the store for a given value. It returns a
list of pairs, each pair consisting of a path together with the matching data.
It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *value*: This specifies the value to look for.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
ifindval
########
ifindval()
::::::::::
This interactive command is used to search the store for a value given by an
"i-pattern". An "i-pattern" is a list of space separated sub-strings. All
strings that contain all of these sub-strings in any order (compared case
insensitive) match. The command lists all paths together with the values whose
string representation matches the given i-pattern. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *val_pattern*: This specifies the i-pattern.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw", "hidelinks", "marklinks". In aligned
format paths and values are printed separated by a colon ":" where the colons
are aligned in the same column making the output better readable. The default
for this parameter is "aligned:hidelinks".
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> ifindval("antiparallel", pattern="id-data.**")
id-data.U2.operation.h_mode_label_2 : antiparallel+
id-data.U2.operation.h_mode_label_3 : antiparallel-
id-data.UE112.operation.h_mode_label_2 : antiparallel+
id-data.UE112.operation.h_mode_label_3 : antiparallel-
id-data.UE46.operation.h_mode_label_1 : antiparallel
id-data.UE49.operation.h_mode_label_2 : antiparallel+
id-data.UE49.operation.h_mode_label_3 : antiparallel-
id-data.UE52.operation.h_mode_label_1 : antiparallel
id-data.Ubonsai.operation.h_mode_label_2: antiparallel+
id-data.Ubonsai.operation.h_mode_label_3: antiparallel-
> ifindval("antiparallel mode")
id-metadata.parameter-info.has_AP_mode.description: antiparallel operation mode exists
txt.ifindval()
::::::::::::::
This command returns the text that `ifindval()`_ prints
to the console as a string. For an explanation of parameters look at the
description of `ifindval()`_.
Here is an example::
> print txt.ifindval('V0 5 4')
id-data.UE112.config.gap2cc_nflags_10 : 4,V0,H5
id-data.UE112.config.gap2cc_nflags_20 : 14,V0,H5
id-data.UE112.config.gap2cc_nflags_5 : 5,V0,H4
id-data.UE49.config.gap2cc_nflags_10 : 4,V0,H5
id-data.UE49.config.gap2cc_nflags_5 : 5,V0,H4
id-data.UE52.config.gap2cc_nflags_10 : 4,V0,H5
id-data.UE52.config.gap2cc_nflags_5 : 5,V0,H4
id-data.Ubonsai.config.gap2cc_nflags_10: 4,V0,H5
id-data.Ubonsai.config.gap2cc_nflags_5 : 5,V0,H4
fun.ifindval()
::::::::::::::
The command ifindval is used to search the store for a value given by an
"i-pattern". An "i-pattern" is a list of space separated sub-strings. All
strings that contain all of these sub-strings in any order (compared case
insensitive) match. It returns a list of pairs, each pair consisting of a path
together with the matching data. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The command
takes the following parameters:
- *val_pattern*: This specifies the i-pattern.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
rxfindval
#########
rxfindval()
:::::::::::
This interactive command is used to search the store for a value given by a
regular expression. It lists all paths together with the values whose string
representation match the given regular expression. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *val_pattern*: This specifies the regular expression. See the python documentation
for `regular expression syntax `_.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw", "hidelinks", "marklinks". In aligned
format paths and values are printed separated by a colon ":" where the colons
are aligned in the same column making the output better readable. The default
for this parameter is "aligned:hidelinks".
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here is an example::
> rxfindval(r'0.*V0.*H')
id-data.UE112.config.gap2cc_nflags_0 : 0,V0,H4
id-data.UE112.config.gap2cc_nflags_6 : 0,V0,H5
id-data.UE46.config.gap2cc_nflags_0 : 0,V0,H2
id-data.UE46.config.gap2cc_nflags_6 : 0,V0,H3
id-data.UE49.config.gap2cc_nflags_6 : 0,V0,H5
id-data.UE52.config.gap2cc_nflags_0 : 0,V0,H4
id-data.UE52.config.gap2cc_nflags_6 : 0,V0,H5
id-data.UE56/1.config.gap2cc_nflags_0 : 0,V0,H0
id-data.UE56/2.config.gap2cc_nflags_0 : 0,V0,H0
id-data.UE56R.config.gap2cc_nflags_0 : 0,V0,H0
id-data.Ubonsai.config.gap2cc_nflags_6: 0,V0,H5
> rxfindval(r'0.*V0.*H', pattern="id-data.*.*.gap2cc_nflags_0")
id-data.UE112.config.gap2cc_nflags_0 : 0,V0,H4
id-data.UE46.config.gap2cc_nflags_0 : 0,V0,H2
id-data.UE52.config.gap2cc_nflags_0 : 0,V0,H4
id-data.UE56/1.config.gap2cc_nflags_0: 0,V0,H0
id-data.UE56/2.config.gap2cc_nflags_0: 0,V0,H0
id-data.UE56R.config.gap2cc_nflags_0 : 0,V0,H0
txt.rxfindval()
:::::::::::::::
This command returns the text that `rxfindval()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`rxfindval()`_.
Here is an example::
> print txt.rxfindval(r'0.*V0.*H5')
id-data.UE112.config.gap2cc_nflags_6 : 0,V0,H5
id-data.UE49.config.gap2cc_nflags_6 : 0,V0,H5
id-data.UE52.config.gap2cc_nflags_6 : 0,V0,H5
id-data.Ubonsai.config.gap2cc_nflags_6: 0,V0,H5
fun.rxfindval()
:::::::::::::::
The command rxfindval is used to search the store for a value given by a
regular expression. It returns a list of pairs, each pair consisting of a
matching path together with the data. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The command
takes the following parameters:
- *val_pattern*: This specifies the regular expression. See the python documentation
for `regular expression syntax `_.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *pattern*: If this parameter is given, it must be a match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here is an example::
> import pprint
> pprint.pprint(fun.rxfindval(r'0.*V0.*H5'))
[('id-data.UE49.config.gap2cc_nflags_6', '0,V0,H5'),
('id-data.UE52.config.gap2cc_nflags_6', '0,V0,H5'),
('id-data.Ubonsai.config.gap2cc_nflags_6', '0,V0,H5'),
('id-data.UE112.config.gap2cc_nflags_6', '0,V0,H5')]
.. _SDpyshell-get:
get
###
get()
:::::
This interactive command prints the value for a given pattern or list of
patterns of a StructuredDataContainer. Note that a path is just a special case
of a pattern so you can use this command to simply print a single value. It
usually uses the global StructuredDataContainer ":ref:`fun.SDC
`". This command prints the value referenced which
may be a simple value (scalar) or a structure (collection), see also :ref:`help
`. If only one path matched the command
prints the single value, if more than one path matched it prints a list of
values. The command takes the following parameters:
- *pattern*: This is a path, a pattern or a list of paths or a list of
patterns. For patterns see also
:ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw", "hidelinks", "marklinks". "raw" means that
the value is simply printed without enclosing quotes or anything. The default
is "raw:hidelinks".
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> get("id-data.U2.names.devicename")
U2IV
> get("id-data.U2.names.devicename", "py")
'U2IV'
> get("id-data.U2.names")
{'devicename': 'U2IV', 'prefix': 'idcp98', 'name': 'U2', 'key': 98}
> get("id-data.U2.names", "yaml")
devicename: U2IV
key: 98
name: U2
prefix: idcp98
> get("id-data.*.names.key")
[96, 3, 110, 98, 97, 95, 12, 80, 7, 15, 13, 10, 8, 9, 11, 5, 81, 99]
txt.get()
:::::::::
This command returns the text that `get()`_ prints to the console as a string.
For an explanation of parameters look at the description of `get()`_.
Here is an example::
> print txt.get("id-data.U2.names")
{'devicename': 'U2IV', 'prefix': 'idcp98', 'name': 'U2', 'key': 98}
fun.get()
:::::::::
The function get returns the value for a given pattern or list of patterns of a
StructuredDataContainer. Note that a path is just a special case of a pattern
so you can use this function to simply get a single value. It usually uses the
global StructuredDataContainer ":ref:`fun.SDC `". This
function returns the value referenced which may be a simple value (scalar) or a
structure (collection), see also
:ref:`help `. If only one path matched
the function returns a single value, if more than one path matched it returns a
list of values. The command takes the following parameters:
- *pattern*: This is a path, a pattern or a list of paths or a list of
patterns. For patterns see also
:ref:`patterns `.
- *show_links*: If this parameter is True, all links in the path are marked
with a '*' character. See also `Marking links`_. The default for this
parameter is False.
- *paths*: This optional parameter is used to provide a list of paths. If this
parameter is given, not the complete StructuredDataContainer is searched but
only all paths in this list.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> import pprint
> pprint.pprint(fun.get("id-data.U2.names")
{'devicename': 'U2IV', 'key': 98, 'name': 'U2', 'prefix': 'idcp98'}
> pprint.pprint(fun.get(["id-data.U2.names", "id-data.U49/1.names"]))
[{'devicename': 'U2IV', 'key': 98, 'name': 'U2', 'prefix': 'idcp98'},
{'devicename': 'U49ID4R', 'key': 7, 'name': 'U49/1', 'prefix': 'idcp7'}]
> pprint.pprint(fun.get("id-data.*.names.key")
[96, 3, 110, 98, 97, 95, 12, 80, 7, 15, 13, 10, 8, 9, 11, 5, 81, 99]
getlinks
########
getlinks()
::::::::::
This interactive command returns a list of all paths that refer to the same
object as the given path. It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". The default is "yaml".
- *include*: This parameter may be used to specify a *pattern* that all
returned paths must match. Only paths that match this pattern are returned.
See also :ref:`patterns `.
- *exclude*: This parameter may be used to specify a *pattern* that all
returned paths must not match. Only paths that do not match this pattern are
returned. *include* and *exclude* may be combined.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here are some examples::
> getlinks("01_facility[0]")
- 01_facility[0]
- 03_subdomain[0].domain.facility
- 03_subdomain[171].domain.facility
- 03_subdomain[1].domain.facility
- 03_subdomain[2].domain.facility
- 03_subdomain[3].domain.facility
- 03_subdomain[4].domain.facility
- 03_subdomain[5].domain.facility
- 03_subdomain[6].domain.facility
- 03_subdomain[7].domain.facility
- 03_subdomain[8].domain.facility
> getlinks("01_facility[0]", exclude="03_subdomain.*.domain.facility")
- 01_facility[0]
> getlinks("01_facility[0]", include="*[0].*.*")
- 03_subdomain[0].domain.facility
txt.getlinks()
::::::::::::::
This command returns the text that `getlinks()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`getlinks()`_.
Here is an example::
> print txt.getlinks("01_facility[0]", include="*[0].*.*")
- 03_subdomain[0].domain.facility
fun.getlinks()
::::::::::::::
This function returns a list of all paths that refer to the same object as the
given path. It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *include*: This parameter may be used to specify a *pattern* that all
returned paths must match. Only paths that match this pattern are returned.
See also :ref:`patterns `.
- *exclude*: This parameter may be used to specify a *pattern* that all
returned paths must not match. Only paths that do not match this pattern are
returned. *include* and *exclude* may be combined.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here is an example::
> import pprint
> pprint.pprint(fun.getlinks("01_facility[0]"))
['01_facility[0]',
'03_subdomain[0].domain.facility',
'03_subdomain[171].domain.facility',
'03_subdomain[1].domain.facility',
'03_subdomain[2].domain.facility',
'03_subdomain[3].domain.facility',
'03_subdomain[4].domain.facility',
'03_subdomain[5].domain.facility',
'03_subdomain[6].domain.facility',
'03_subdomain[7].domain.facility',
'03_subdomain[8].domain.facility']
findlinks
#########
findlinks()
:::::::::::
This command for interactive use returns a list of lists of paths that refer to
the same object. At least one path in each sublist matches the given pattern.
It usually uses the global StructuredDataContainer ":ref:`fun.SDC
`". The command takes the following parameters:
- *pattern*: This specifies the match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". The default is "yaml".
- *include*: This parameter may be used to specify a *pattern* that all
returned paths must match. Only paths that match this pattern are returned.
- *exclude*: This parameter may be used to specify a *pattern* that all
returned paths must not match. Only paths that do not match this pattern are
returned. *include* and *exclude* may be combined.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here is an example::
> findlinks("01_facility.*")
- - 01_facility[0]
- 03_subdomain[0].domain.facility
- 03_subdomain[171].domain.facility
- 03_subdomain[1].domain.facility
- 03_subdomain[2].domain.facility
- 03_subdomain[3].domain.facility
- 03_subdomain[4].domain.facility
- 03_subdomain[5].domain.facility
- 03_subdomain[6].domain.facility
- 03_subdomain[7].domain.facility
- 03_subdomain[8].domain.facility
- - 01_facility[1]
- 02_domain[23].facility
- 03_subdomain[137].domain.facility
- 03_subdomain[140].domain.facility
- 03_subdomain[141].domain.facility
- 03_subdomain[142].domain.facility
- 03_subdomain[165].domain.facility
- 03_subdomain[169].domain.facility
- - 01_facility[2]
- 02_domain[14].facility
- 02_domain[16].facility
- 02_domain[18].facility
- 03_subdomain[103].domain.facility
- 03_subdomain[108].domain.facility
- 03_subdomain[111].domain.facility
- 03_subdomain[167].domain.facility
- 03_subdomain[94].domain.facility
- 03_subdomain[97].domain.facility
- 03_subdomain[99].domain.facility
txt.findlinks()
:::::::::::::::
This command returns the text that `findlinks()`_ prints
to the console as a string. For an explanation of parameters look at the
description of `findlinks()`_.
fun.findlinks()
:::::::::::::::
This command returns a list of lists of paths that refer to the same object. At
least one path in each sublist matches the given pattern. It usually uses the
global StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *pattern*: This specifies the match pattern. Only data
that matches this pattern is examined. Note that your pattern usually should
end with ".**" in order get all paths that *start* with the pattern.
See also :ref:`patterns `.
- *include*: This parameter may be used to specify a *pattern* that all
returned paths must match. Only paths that match this pattern are returned.
- *exclude*: This parameter may be used to specify a *pattern* that all
returned paths must not match. Only paths that do not match this pattern are
returned. *include* and *exclude* may be combined.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here is an example::
> pprint.pprint(fun.findlinks("01_facility.*")
[['01_facility[0]',
'03_subdomain[0].domain.facility',
'03_subdomain[171].domain.facility',
'03_subdomain[1].domain.facility',
'03_subdomain[2].domain.facility',
'03_subdomain[3].domain.facility',
'03_subdomain[4].domain.facility',
'03_subdomain[5].domain.facility',
'03_subdomain[6].domain.facility',
'03_subdomain[7].domain.facility',
'03_subdomain[8].domain.facility'],
['01_facility[1]',
'02_domain[23].facility',
'03_subdomain[137].domain.facility',
'03_subdomain[140].domain.facility',
'03_subdomain[141].domain.facility',
'03_subdomain[142].domain.facility',
'03_subdomain[165].domain.facility',
'03_subdomain[169].domain.facility'],
['01_facility[2]',
'02_domain[14].facility',
'02_domain[16].facility',
'02_domain[18].facility',
'03_subdomain[103].domain.facility',
'03_subdomain[108].domain.facility',
'03_subdomain[111].domain.facility',
'03_subdomain[167].domain.facility',
'03_subdomain[94].domain.facility',
'03_subdomain[97].domain.facility',
'03_subdomain[99].domain.facility']]
Modifying the data
++++++++++++++++++
filter_out
##########
filter_out()
::::::::::::
This interactive command is used to filter out data in a
StructuredDataContainer. It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". All parts that do not match the
given pattern are removed. The command takes the following parameters:
- *pattern*: This specifies the filter pattern. Note that in oder tp match all
paths *starting* with that pattern you have to end the pattern with ".**".
See also :ref:`patterns `.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
This function always returns the StructuredDataContainer where the data was
changed.
Here are some examples::
filter_out("mykey1.mykey2")
filter_out("mykey1.*")
filter_out("mykey1.*.mykey2.*.mykey3")
txt.filter_out()
::::::::::::::::
This command is identical to `filter_out()`_ except that it doesn't print a
message to the console.
fun.filter_out()
::::::::::::::::
This command is identical to `filter_out()`_ except that it doesn't print a
message to the console.
change
######
change()
::::::::
This interactive command is used to change a single value for a specific path
or a list of paths of a StructuredDataContainer. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *value*: This is the value to be set.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here are some examples::
> get("id-data.U2.global.device_status")
simulated
> change("id-data.U2.global.device_status", "installed")
> get("id-data.U2.global.device_status")
installed
txt.change()
::::::::::::
This command is identical to `change()`_.
fun.change()
::::::::::::
This command is identical to `change()`_.
put
###
put()
:::::
This interactive command is used to change or add a single value for a specific
path or a list of paths of a StructuredDataContainer. It usually uses the
global StructuredDataContainer ":ref:`fun.SDC `". If
the path is not present in the StructuredDataContainer, missing elements are
created on the fly. The command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *value*: This is the value to be set.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here is an example::
> find("id-data.U2.global.**")
id-data.U2.global.description : U2 ,U2IV ,idcp98,pseudo ID for A.Pohl
id-data.U2.global.device_status: installed
id-data.U2.global.id-key : 98
id-data.U2.global.instance_no : 0
id-data.U2.global.primary_key : 37
id-data.U2.global.undulator : U2
> put("id-data.U2.global.extra", 100)
> find("id-data.U2.global.**")
id-data.U2.global.description : U2 ,U2IV ,idcp98,pseudo ID for A.Pohl
id-data.U2.global.device_status: installed
id-data.U2.global.extra : 100
id-data.U2.global.id-key : 98
id-data.U2.global.instance_no : 0
id-data.U2.global.primary_key : 37
id-data.U2.global.undulator : U2
txt.put()
:::::::::
This command is identical to `put()`_.
fun.put()
:::::::::
This command is identical to `put()`_.
delete
######
delete()
::::::::
This interactive command is used to delete a single value of a given path or a
list of paths of a StructuredDataContainer. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *path*: This specifies the path or a list of paths. See also
:ref:`paths `.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here is an example::
> find("id-data.U2.global.**")
id-data.U2.global.description : U2 ,U2IV ,idcp98
id-data.U2.global.device_status: installed
id-data.U2.global.id-key : 98
id-data.U2.global.instance_no : 0
id-data.U2.global.primary_key : 37
id-data.U2.global.undulator : U2
> delete("id-data.U2.global.description")
> find("id-data.U2.global.**")
id-data.U2.global.device_status: installed
id-data.U2.global.id-key : 98
id-data.U2.global.instance_no : 0
id-data.U2.global.primary_key : 37
id-data.U2.global.undulator : U2
txt.delete()
::::::::::::
This command is identical to `delete()`_.
fun.delete()
::::::::::::
This command is identical to `delete()`_.
link
####
link()
::::::
This interactive command is used to let a path in the StructuredDataContainer
refer to the same data as another already existing path. It usually uses the
global StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *from_path*: This specifies the path or a list of paths whose value is
changed. The path is a list of keys joined with a dot '.'. If the keys
contain one of the characters '.[]' these have to be prepended with a
backslash "\\". If the path doesn't already exist it is created, even missing
elements within a longer path are created on the fly.
- *to_path*: This specifies the path whose node is referenced. This path must
exist in the StructuredDataStore. The path is a list of keys joined with a
dot '.'. If the keys contain one of the characters '.[]' these have to be
prepended with a backslash "\\".
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here is an example::
> find("id-data.U2.interface.**", "marklinks")
id-data.U2.interface.base_panel : opi_baseIT.adl
id-data.U2.interface.h_axle_scheme: 1342
id-data.U2.interface.user_panel : opi_usrIT.adl
> link("id-data.U2.new", "id-data.U2.interface")
> find("id-data.U2.new.**", "marklinks")
id-data.U2.new*.base_panel : opi_baseIT.adl
id-data.U2.new*.h_axle_scheme: 1342
id-data.U2.new*.user_panel : opi_usrIT.adl
txt.link()
::::::::::
This command is identical to `link()`_.
fun.link()
::::::::::
This command is identical to `link()`_.
Querying types
++++++++++++++
typepaths
#########
typepaths()
:::::::::::
This interactive command used to print paths of the StructuredDataTypes object.
It usually uses the global StructuredDataContainer ":ref:`fun.SDC
`". Only paths that match the given pattern are
printed. The command takes the following parameters:
- *pattern*: This specifies the match pattern. Only data that matches this
pattern is examined. Note that if your pattern ends with ".**" you get
typepaths that *start* with the pattern.
See also :ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "raw". The default is "yaml".
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> typepaths("id-data.*")
- id-data.*
> typepaths("id-data.*.*")
- id-data.*.config
- id-data.*.feedback
- id-data.*.global
- id-data.*.interface
- id-data.*.measurement
- id-data.*.names
- id-data.*.network
- id-data.*.operation
- id-data.*.physical
- id-data.*.referencing
- id-data.*.version
txt.typepaths()
:::::::::::::::
This command returns the text that `typepaths()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`typepaths()`_.
Here is an example::
> print txt.typepaths("id-data.*.version")
- id-data.*.version
fun.typepaths()
:::::::::::::::
This function returns a list of paths of the StructuredDataTypes object that
match the given pattern. It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The function takes the following
parameters:
- *pattern*: This specifies the match pattern. Only data that matches this
pattern is examined. Note that if your pattern ends with ".**" you get
typepaths that *start* with the pattern.
See also :ref:`patterns `.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
typefind
########
typefind()
::::::::::
This interactive command used to search the StructuredDataTypes object for a
given pattern. It lists all matching paths together with the type
specification. It usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *pattern*: This specifies the match pattern. Only data that matches this
pattern is examined. Note that if your pattern ends with ".**" you get
typepaths that *start* with the pattern.
See also :ref:`patterns `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "csv", "aligned", "raw". In aligned format paths and values are
printed separated by a colon ":" where the colons are aligned in the same
column making the output better readable. The default for this parameter is
"aligned".
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here is an example::
> typefind("id-data.*.names.*")
id-data.*.names.devicename: string
id-data.*.names.key : integer
id-data.*.names.name : string
id-data.*.names.prefix : string
txt.typefind()
::::::::::::::
This command returns the text that `typefind()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`typefind()`_.
Here is an example::
> print txt.typefind("id-data.*.names.*")
id-data.*.names.devicename: string
id-data.*.names.key : integer
id-data.*.names.name : string
id-data.*.names.prefix : string
fun.typefind()
::::::::::::::
This command is used to search the StructuredDataTypes object for a given
pattern. It returns a list of pairs, each pair consisting of a matching path
together with the type specification. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The command
takes the following parameters:
- *pattern*: This specifies the match pattern. Only data that matches this
pattern is examined. Note that if your pattern ends with ".**" you get
typepaths that *start* with the pattern.
See also :ref:`patterns `.
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
typeget
#######
typeget()
:::::::::
This interactive command prints that type declaration for a given path. It
usually uses the global StructuredDataContainer ":ref:`fun.SDC
`". The command takes the following parameters:
- *path*: This specifies the path. See also :ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". "raw" means that the value is simply printed without
enclosing quotes or anything. The default is "yaml".
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> typeget("id-data.*.names.devicename")
string
...
> typeget("id-data.*.names")
optional_struct:
- devicename
- key
- name
- prefix
txt.typeget()
:::::::::::::
This command returns the text the `typeget()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`typeget()`_.
Here is an example::
> print txt.typeget("id-data.*.names")
optional_struct:
- devicename
- key
- name
- prefix
fun.typeget()
:::::::::::::
This command returns the type declaration for a given path. The type
declaration may be a scalar or a list or a map, depending on the type. It
usually uses the global StructuredDataContainer
":ref:`fun.SDC `". The command takes the following
parameters:
- *path*: This specifies the typepath. The path is a list of keys and wildcards
joined with a dot '.'. If the keys contain one of the characters '.[]' these
have to be prepended with a backslash "\\".
- *sdc*: The source of the data. If this parameter is omitted, the data is
taken from the global variable ":ref:`fun.SDC `".
Here are some examples::
> print fun.typeget("id-data.*.names.devicename")
string
> print fun.typeget("id-data.*.names")
{'optional_struct': ['devicename', 'key', 'name', 'prefix']}
Modifying types
+++++++++++++++
typeput
#######
typeput()
:::::::::
This interactive command is used to change or add a type declaration. The
command gets a path or pattern and a type declaration that may be a string or a
map. The map should be provided in python syntax but the simplified strings of
functional python may be used. The command takes the following parameters:
- *path*: This specifies the path. See also :ref:`paths `.
- *value*: This is the value to be set. See also the examples further below.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here are some examples:
All values for paths matching "id-data.*.global.remark" must be strings::
typeput("id-data.*.global.remark", "string")
All values for paths matching "id-data.*.facility" must be of type "struct"
with the fields "description", "name" and "facility::
typeput("id-data.*.facility", {"struct" : ["description", "name", "facility"]}
Note that due to the usage of simplified strings here, the spaces around the
second colon and the space before the closing square brackets must not be
omitted.
txt.typeput()
:::::::::::::
This command is identical to `typeput()`_.
fun.typeput()
:::::::::::::
This command is identical to `typeput()`_.
typeadditem
###########
typeadditem()
:::::::::::::
This interactive command is used to add an item to a complex type in a simple
way. Types like "struct" have a list of fields attached. With this command you
can add a field to the existing list without the need to mention all the fields
that exist already as you would have to when using typeput. The command usually
uses the global StructuredDataContainer ":ref:`fun.SDC
`". It takes the following parameters:
- *path*: This specifies the path. See also :ref:`paths `.
- *value*: This is the string value to be added. See also the examples further
below.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here are some examples:
This is the existing type declaration::
> typeget("id-data.*.network")
optional_struct:
- bootserver
- gateway
- ioc
- mount_filesystem
- ntpserver
- sec_lswitch_hosts
Now we add a new field to the list::
> typeadditem("id-data.*.network", "netmask")
An here we check the results::
> typeget("id-data.*.network")
optional_struct:
- bootserver
- gateway
- ioc
- mount_filesystem
- netmask
- ntpserver
- sec_lswitch_hosts
txt.typeadditem()
:::::::::::::::::
This command is identical to `typeadditem()`_.
fun.typeadditem()
:::::::::::::::::
This command is identical to `typeadditem()`_.
typedelete
##########
typedelete()
::::::::::::
This interactive command is used to delete a type. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". The
command takes the following parameters:
- *path*: This specifies the path. See also :ref:`paths `.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
txt.typedelete()
::::::::::::::::
This command is identical to `typedelete()`_.
fun.typedelete()
::::::::::::::::
This command is identical to `typedelete()`_.
typedeleteitem
##############
typedeleteitem()
::::::::::::::::
This interactive command is used to remove an item from a complex type in a
simple way. Types like "struct" have a list of fields attached. With this
command you can remove a field from the existing list without the need to
mention all the fields that exist already as you would have to when using
typeput. The command usually uses the global StructuredDataContainer
":ref:`fun.SDC `". It takes the following
parameters:
- *path*: This specifies the path. See also :ref:`paths `.
- *value*: This is the string value to be removed. See also the examples
further below.
- *sdc*: The StructuredDataContainer that is modified. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is modified.
Here are some examples:
First we check how the type declaration for path "id-data.*.names" looks like::
> typeget("id-data.*.names")
optional_struct:
- devicename
- key
- name
- prefix
Now we remove the item "facility"::
> typedeleteitem("id-data.*.names", "key")
And here we check the results::
> typeget("id-data.*.names")
optional_struct:
- devicename
- name
- prefix
txt.typedeleteitem()
::::::::::::::::::::
This command is identical to `typedeleteitem()`_.
fun.typedeleteitem()
::::::::::::::::::::
This command is identical to `typedeleteitem()`_.
Typechecking
++++++++++++
typecheck
#########
typecheck()
:::::::::::
This interactive command is used to check the data in a StructuredDataContainer
against it's type specifications. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `". This
command takes no parameters.
- *sdc*: The StructuredDataContainer that is checked. If this parameter is
omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is checked.
txt.typecheck()
:::::::::::::::
This command is identical to `typecheck()`_.
fun.typecheck()
:::::::::::::::
This command is identical to `typecheck()`_.
typematch
#########
typematch()
:::::::::::
This interactive command shows if one of the type checks matches a given path
and shows the type specification. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `".
The command takes the following parameters:
- *path*: This specifies the path. See also :ref:`paths `.
- *formatspec*: The format specification. Allowed format keywords here are:
"yaml", "py", "raw". The default is "yaml".
- *sdc*: The StructuredDataContainer where the path and the matching type are
searched. If this parameter is omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is taken.
Here is an example::
> typematch("id-data.UE56R.names.devicename")
id-data.*.names.devicename: string
txt.typematch()
:::::::::::::::
This command returns the text that `typematch()`_ prints to the console as a
string. For an explanation of parameters look at the description of
`typematch()`_.
Here is an example::
> print txt.typematch("id-data.UE56R.names.devicename")
id-data.*.names.devicename: string
fun.typematch()
:::::::::::::::
The function fun.typematch returns the type declarations that match a given
path and shows the type specification. It usually uses the global
StructuredDataContainer ":ref:`fun.SDC `".
The command takes the following parameters:
- *path*: This specifies the typepath. The path is a list of keys and wildcards
joined with a dot '.'. If the keys contain one of the characters '.[]' these
have to be prepended with a backslash "\\".
- *sdc*: The StructuredDataContainer where the path and the matching type are
searched. If this parameter is omitted, the global StructuredDataContainer
":ref:`fun.SDC `" is taken.
Here are some examples::
> print fun.typematch("id-data.UE56R.names.devicename")
{'id-data.*.names.devicename': 'string'}
> import pprint
> pprint.pprint(fun.typematch("id-data.UE56R.names"))
{'id-data.*.names': {'optional_struct': ['devicename',
'key',
'name',
'prefix']}}
Command aliases
---------------
These are aliases for the commands described above:
- h : help,
- r : read,
- p : pr,
- w : write,
- rw : rewrite,
Invoking SDpyshell
------------------
Here is a short overview on the SDpyshell command line options:
--version show program's version number and exit
-h, --help show this help message and exit
--summary Print a summary of the function of the program.
-p COMMANDS, --precmd=COMMANDS
specify COMMANDS to perform before any other action
--precmdfile=FILE specify a FILE to execute before any other action
-c COMMANDS, --cmd=COMMANDS
specify COMMANDS to perform
-f FILE, --file FILE load the specified StructuredData FILE. You may add the
formatspec directly with a comma.
-M MODULE, --module=MODULE
specify a MODULE to import at make its functions
accessible by XMLRPC
-I DIRECTORY, --searchpath=DIRECTORY
specify a DIRECTORY to prepend it to the module search
path.
--no-locking do not lock file accesses
--server=PORT
start in telnetserver mode on port PORT
--localhost start server on 'localhost' instead of DNSDOMAINNAME.
In this case the server can only be contacted from
applications running on the same host.
--pidfile=PIDFILE specify the PIDFILE where PID's of sub processes will
be stored
--kill just kill old servers, do not start new ones.
--password specify the password needed to log onto the server
interactively
--password-hash=HASH specify the HASH of the password needed to log onto
the server
--gen-password-hash=HASH
generate a password HASH from the given string.
Precommands
+++++++++++
Precommands are commands that are executed at the start of the shell before any
other command. These commands can be given as a command line parameter
(--precmd) or they can be read from a file (--precmdfile). A typical
application is to put the command to read a StructuredData file in a file and
provide it's name with --precmdfile. Precommands are also useful when SDpyshell
is started in server mode.
Extensions
++++++++++
These are user supplied python modules that can be loaded by the SDpyshell. The
module name (the filename without ".py") is provided with the command line
option "-M". In this case the python module is loaded and it's functions are
accessible with the module name as a prefix.
You can use command line option "-I" in order to extend the search path for
extensions which are basically python modules. Keep in mind that extensions are
also searched in all paths specified by the "PYTHONPATH" environment variable.
Here is an example:
We have a file "myext.py" with this content::
import StructuredData.SDshelllibTxt as txt
import StructuredData.SDshelllibFun as fun
def ids():
p= fun.paths("id-data.*")
return fun.poppath(p, no=-1)
def print_ids(formatspec="yaml"):
print txt.format(ids(), formatspec)
Now we start SDpyshell with "-M" to load the extension and with "--precmd" to load the
sample StructuredData file from the "samples" directory::
SDpyshell -M myext --precmd 'r("idcp_db.cache.SDCyml")'
> import pprint
> pprint.pprint(myext.ids())
['U125/1',
'U125/2',
'U139',
'U2',
'U3',
'U4',
'U41',
'U48',
'U49/1',
'U49/2',
'UE112',
'UE46',
'UE49',
'UE52',
'UE56/1',
'UE56/2',
'UE56R',
'Ubonsai']
> myext.print_ids("yaml")
- U125/1
- U125/2
- U139
- U2
- U3
- U4
- U41
- U48
- U49/1
- U49/2
- UE112
- UE46
- UE49
- UE52
- UE56/1
- UE56/2
- UE56R
- Ubonsai
Server mode
+++++++++++
When option "-s" is provided, SDpyshell is started in server mode. It waits for
connections on the specified port.
Note that since SDpyshell includes a complete python interpreter, unauthorized
access to your SDpyshell server may pose a security risk. Anyone who can connect
to the server can execute arbitrary python commands under your user id. This is
the reason why specifying a password is mandatory when SDpyshell is started in
server mode. If you want a server with a restricted set of commands you might
consider using SDxmlrpc.
You can simply use telnet as a client to connect to the SDpyshell server. If you
have `rlwrap `_ installed you can connect
with::
rlwrap -r telnet [host] [port]
With rlwrap you have command line history and command completion. Note that for
terminating the connection you have to enter "quit" on the command line.
Server password
+++++++++++++++
For security reasons you always have to provide a password when you start
SDpyshell in server mode. The password can be entered interactively when you
start SDpyshell with the "--password" option. With "--password-hash" you can
specify a password hash on the command line, a long hexadecimal string. With
"--gen-password-hash" you can generate the hexadecimal string from a given
password. "--password-hash" is useful when the SDpyshell server is started from a
script since you can not regenerate the password from the password hash.
Process management
++++++++++++++++++
When SDpyshell is started as a server it is useful to know the process id (PID)
of the server and to be able to restart the server by killing the old one and
starting a new one. This is done with the options --pidfile and --kill combined
with -s. --pidfile is used to specify the name of a PID file, this file
contains a line with the process id (PID) of the server and the command that
was used to start the server. When SDpyshell is started in server mode and
--pidfile is provided, the process named in this file (and it's children) are
killed first. When SDpyshell is started, it's PID and command line are put to
the PID file. If you dont't want to restart an SDpyshell server but just want
to kill the old one, use --pidfile together with --kill.