| | |
- asrt_options(opt)
- assert that a parameter is an instance of the Options class.
Here are some examples:
>>> asrt_options(Options())
>>> asrt_options(1)
Traceback (most recent call last):
...
TypeError: object of class "Options" expected
- default_dumper(val, indent, options=None)
- dumps an unknown value.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
The function returns list of a single string which represents
the given data. It is a very simple dump function used for
types that are unknown to rdump.
Here are some examples:
first we define a print-function:
>>> def pr(l):
... print list2str(l)
>>> pr(default_dumper("ABC",10,Options(format=REPR,start=False)))
<OBJ: 'ABC'>
>>> pr(default_dumper([1,2],10,Options(format=REPR,start=False)))
<OBJ: [1, 2]>
>>> pr(default_dumper([1,2],10,Options(format=STR,start=False)))
<BLANKLINE>
<OBJ: [1, 2]>
>>> pr(default_dumper([1,2],10,Options(format=STR,start=True)))
<OBJ: [1, 2]>
- dict_dumper(val, indent, options=(rdump.Options: 'format' : 0, 'indent_inc' : 4, 'key_indent' : 4, 'start' : True ))
- dumps a dict value.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
The function returns a nested list of strings which represent
the dictionary data. The function returns <None> if <val>
is not a dictionary. This function is usually not called
by external programs.
Here are some examples. First we define a simple
dictionary:
>>> a={"A":1,"C":5,"B":2, "kjhkjhkh":12123}
The nested string list returned by dict_dumper looks like this:
>>> dict_dumper(a,0)
['{ ', [["'A' : ", ['1']], [', '], ["'B' : ", ['2']], [', '], ["'C' : ", ['5']], [', '], ["'kjhkjhkh' : ", ['12123']]], ' }']
Converted to a string the result looks like this:
>>> list2str(dict_dumper(a,0))
"{ 'A' : 1, 'B' : 2, 'C' : 5, 'kjhkjhkh' : 12123 }"
Printed in "STR" format it looks like this:
>>> print list2str(dict_dumper(a,0,Options(format=STR)))
{
'A' :
1,
'B' :
2,
'C' :
5,
'kjhkjhkh' :
12123
}
Now we define a more complicated dictionary which
contains another dictionary:
>>> a={"A":1,"C":5,"B":{"XX":12,"YY":13}, "kjhkjhkh":12123}
Printed in "REPR" format it looks like this:
>>> print list2str(dict_dumper(a,0,Options(format=REPR)))
{ 'A' : 1, 'B' : { 'XX' : 12, 'YY' : 13 }, 'C' : 5, 'kjhkjhkh' : 12123 }
Printed in "STR" format it looks like this:
>>> print list2str(dict_dumper(a,0,Options(format=STR, indent_inc=8)))
{
'A' :
1,
'B' :
{
'XX' :
12,
'YY' :
13
},
'C' :
5,
'kjhkjhkh' :
12123
}
Printed in "STR_D" format it looks like this:
>>> print list2str(dict_dumper(a,0,Options(format=STR_D, indent_inc=8)))
{
'A' : 1,
'B' :
{
'XX' : 12,
'YY' : 13
},
'C' : 5,
'kjhkjhkh' : 12123
}
Here we print in "STR_D" format with a different value for key_indent.
The value for indent_inc
>>> print list2str(dict_dumper(a,0,Options(format=STR_D, indent_inc=4,key_indent=12)))
{
'A' : 1,
'B' :
{
'XX' : 12,
'YY' : 13
},
'C' : 5,
'kjhkjhkh' : 12123
}
- drepr(val, indent=0)
- convert val to a dumpstring, using the "REPR" format.
parameters:
val -- the value for which the dumpstring is created
indent -- indentation (optional)
Here is an example:
>>> print drepr([1,{"A":[2,3]},"XY"])
[ 1, { 'A' : [ 2, 3 ] }, 'XY' ]
- dstr(val, indent=0)
- convert val to a dumpstring, using the "STR" format.
parameters:
val -- the value for which the dumpstring is created
indent -- indentation (optional)
Here is an example:
>>> print dstr([1,{"A":[2,3]},"XY"])
[
1,
{
'A' :
[
2,
3
]
},
'XY'
]
- dstrd(val, indent=0)
- convert val to a dumpstring, using the "STR_D" format.
parameters:
val -- the value for which the dumpstring is created
indent -- indentation (optional)
Here is an example:
>>> print dstrd([1,{"A":[2,3]},"XY"])
[
1,
{
'A' :
[
2, 3
]
},
'XY'
]
- dump(val, indent=0, options=(rdump.Options: 'format' : 0, 'indent_inc' : 4, 'key_indent' : 4, 'start' : True ))
- converts val to a multi-line string and prints it.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
This function simply calls dumpstr and prints the result
to the screen.
Here are some examples:
>>> dump({"A":1,"B":[1,2],"C":{"X":10,"Y":11}},options=Options(format=REPR))
{ 'A' : 1, 'B' : [ 1, 2 ], 'C' : { 'X' : 10, 'Y' : 11 } }
>>> dump({"A":1,"B":[1,2],"C":{"X":10,"Y":11}},options=Options(format=STR))
{
'A' :
1,
'B' :
[
1,
2
],
'C' :
{
'X' :
10,
'Y' :
11
}
}
>>> dump({"A":1,"B":[1,2],"C":{"X":10,"Y":11}},options=Options(format=STR_D))
{
'A' : 1,
'B' :
[
1, 2
],
'C' :
{
'X' : 10,
'Y' : 11
}
}
- dumpable_dumper(val, indent, options=None)
- dumps a Dumpable object.
Here are some examples:
>>> a= Dumpable()
>>> dumpable_dumper(a,4,Options(format=REPR,start=False))
['(Dumpable)']
- dumpstr(val, indent=0, options=(rdump.Options: 'format' : 0, 'indent_inc' : 4, 'key_indent' : 4, 'start' : True ))
- converts val to a multi-line string and returns it.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
Here are some examples with a simple list:
>>> print dumpstr([1,2],options=Options(format=REPR))
[ 1, 2 ]
>>> print dumpstr([1,2],options=Options(format=STR))
[
1,
2
]
>>> print dumpstr([1,2],indent=4,options=Options(format=STR))
[
1,
2
]
And here are examples with a more complicated list:
>>> print dumpstr(["A",1,[2,3],{"X":1,"Y":2}],options=Options(format=REPR))
[ 'A', 1, [ 2, 3 ], { 'X' : 1, 'Y' : 2 } ]
>>> print dumpstr(["A",1,[2,3],{"X":1,"Y":2}],options=Options(format=STR))
[
'A',
1,
[
2,
3
],
{
'X' :
1,
'Y' :
2
}
]
The "STR_D" format spans several lines, like "STR" but tries to
be more compact by putting simple values in a single line an
placing dictionary values right behind the dictionary keys:
>>> print dumpstr(["A",1,[2,3],{"X":1,"Y":2}],options=Options(format=STR_D))
[
'A', 1,
[
2, 3
],
{
'X' : 1,
'Y' : 2
}
]
- ldump(val, indent=0, options=None)
- the usually INTERNAL recursive dump function.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
returns: a nested list of lists of strings
The function returns a nested list of strings which represent
the data. This function is usually not called by external programs.
Note: the first line is not indented, the last line contains no
carriage return.
Here are some examples:
first we define a print-function:
>>> def pr(l):
... print list2str(l)
>>> pr(ldump("A",10,Options(format=REPR,start=False)))
'A'
>>> pr(ldump([1,2],10,Options(format=REPR,start=False)))
[ 1, 2 ]
>>> pr(ldump("A",10,Options(format=STR,start=False)))
<BLANKLINE>
'A'
>>> pr(ldump("A",10,Options(format=STR,start=True)))
'A'
- list2str(listpar)
- combine a nested list of strings to a single string.
parameters:
listpar -- the (possibly) nested list of strings. The list is
flattened (with putil.flatten) and joined with
"".join(..).
Here is an example:
>>> print list2str(["This"," ",["is"," ",["a"," ","Test"]]])
This is a Test
- list_dumper(val, indent, options=(rdump.Options: 'format' : 0, 'indent_inc' : 4, 'key_indent' : 4, 'start' : True ))
- dumps a list or a tuple value.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
The function returns a nested list of strings which represent
the list data. The function returns <None> if <val>
is not a dictionary. This function is usually not called
by external programs.
Here are some examples:
If the 1st parameter is not an instance of a list, the function returns None:
>>> list_dumper(100,0)
Now we dump a simple list with indentation 0:
>>> a=[1,2,3]
>>> list_dumper(a,0)
['[ ', [['1'], [', '], ['2'], [', '], ['3']], ' ]']
When we convert the result to a string, it looks like this:
>>> list2str(list_dumper(a,0))
'[ 1, 2, 3 ]'
Now we print the list in "STR" format:
>>> print list2str(list_dumper(a,0,Options(format=STR)))
[
1,
2,
3
]
We define a more complicated, nested list:
>>> a=[1,2,["A","B","C"],4,5]
Printed with "REPR" format it looks like this:
>>> print list2str(list_dumper(a,0,Options(format=REPR)))
[ 1, 2, [ 'A', 'B', 'C' ], 4, 5 ]
With "STR" format, we have each element at a single line,
each nested list is indented 4 further characters (the default
for indent_inc is 4):
>>> print list2str(list_dumper(a,0,Options(format=STR)))
[
1,
2,
[
'A',
'B',
'C'
],
4,
5
]
The same with indent_inc set to 8 looks like this:
>>> print list2str(list_dumper(a,0,Options(format=STR,indent_inc=8)))
[
1,
2,
[
'A',
'B',
'C'
],
4,
5
]
The "STR_D" format tries to be more dense and group simple (scalar)
elements in a single line. An element that is not of a simple type
is still printed in a new line with indentation:
>>> print list2str(list_dumper(a,0,Options(format=STR_D,indent_inc=8)))
[
1, 2,
[
'A', 'B', 'C'
],
4, 5
]
Finally an example that this function can also dump tuples, in this case
the square brackets in the output are replaced with round brackets:
>>> a=(1,2,3)
>>> list_dumper(a,0)
['( ', [['1'], [', '], ['2'], [', '], ['3']], ' )']
>>> list2str(list_dumper(a,0))
'( 1, 2, 3 )'
- prepr(val, indent=0)
- dump val using the "REPR" format.
parameters:
val -- the value for which the dumpstring is created
indent -- indentation (optional)
Here is an example:
>>> prepr([1,{"A":[2,3]},"XY"])
[ 1, { 'A' : [ 2, 3 ] }, 'XY' ]
- pstr(val, indent=0)
- dump val using the "STR" format.
parameters:
val -- the value for which the dumpstring is created
indent -- indentation (optional)
Here is an example:
>>> pstr([1,{"A":[2,3]},"XY"])
[
1,
{
'A' :
[
2,
3
]
},
'XY'
]
- pstrd(val, indent=0)
- dump val using the "STR_D" format.
parameters:
val -- the value for which the dumpstring is created
indent -- indentation (optional)
Here is an example:
>>> pstrd([1,{"A":[2,3]},"XY"])
[
1,
{
'A' :
[
2, 3
]
},
'XY'
]
- record_dump_util(key_val_list, indent, key_add_indent, val_add_indent, open_st, close_st, options=None)
- dumps a dict value.
parameters:
key_val_list -- a list of [key,value] sub-lists
indent -- cuttent indentation level of each new started line
key_add_indent -- additional indent for keys
val_add_indent -- additional indent for values
open_st -- opening string
close_st -- closing string
options -- the options object, see "class options"
The function returns a nested list of strings which represent
the data. This function can be used to implement dumper functions
for self-defined classes.
Here are some examples:
First we define a short list of lists:
>>> l=[["k1",1],["k2",2]]
and a print-function:
>>> def pr(l):
... print list2str(l)
>>> pr(record_dump_util(l,10,8,4,"(mytype",")",Options(format=REPR,start=False)))
(mytype 'k1' : 1, 'k2' : 2 )
>>> pr(record_dump_util(l,10,8,4,"(mytype",")",Options(format=REPR,start=True)))
(mytype 'k1' : 1, 'k2' : 2 )
>>> pr(record_dump_util(l,10,8,4,"(mytype",")",Options(format=STR,start=False)))
<BLANKLINE>
(mytype
'k1' :
1,
'k2' :
2
)
>>> pr(record_dump_util(l,10,8,4,"(mytype",")",Options(format=STR,start=True)))
(mytype
'k1' :
1,
'k2' :
2
)
>>> pr(record_dump_util(l,10,8,4,"(mytype",")",Options(format=STR_D,start=False)))
<BLANKLINE>
(mytype
'k1' : 1,
'k2' : 2
)
>>> pr(record_dump_util(l,10,8,4,"(mytype",")",Options(format=STR_D,start=True)))
(mytype
'k1' : 1,
'k2' : 2
)
- register_new_format()
- returns an index for a new format in addition to REPR,STR and STR_D.
This function simply ensures, that an index for a new format is unique.
Here is an example
>>> register_new_format()
3
>>> register_new_format()
4
- replace_dumper(dumpers_index, func)
- replaces the built-in dumpers.
parameters:
dumpers_index -- one of the DUMPERS_IDX_XXXX constants"
func -- this is the dumper function. This function must
be of the type: func(val,indent)
val is the value to dump, indent the indentation
level for each new started line. The function
must return a list of strings which may also
contain nested lists of strings or further nested
lists. The function must test the type of <val>
and return <None> if the type is unknown. The rdump
module will then try other dumper-functions on the
given value.
- scalar_dumper(val, indent, options=(rdump.Options: 'format' : 0, 'indent_inc' : 4, 'key_indent' : 4, 'start' : True ))
- dumps a scalar value.
parameters:
val -- the value to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
The function returns list of a single string which represents
the given scalar data. Scalar means that the type of <val> is
one of: string, int, float, bool or None.
The function returns <None> if <val>
is not a scalar. This function is usually not called
be external programs.
Here are some examples:
If the 1st parameter is not a scalar, the function returns None:
>>> scalar_dumper([1,2],10,Options(format=STR,start=False))
Otherwise it returns a nested stringlist:
>>> scalar_dumper("ABC",0)
["'ABC'"]
>>> scalar_dumper("ABC",10)
["'ABC'"]
>>> scalar_dumper("ABC",10,Options(format=STR))
[' ', "'ABC'"]
>>> scalar_dumper("ABC",10,Options(format=STR,start=False))
['\n', ' ', "'ABC'"]
- set_dumper(func, typename)
- adds a new dumper function.
parameters:
func -- this is the dumper function. This function must
be of the type: func(val,indent)
val is the value to dump, indent the indentation
level for each new started line. The function
must return a list of strings which may also
contain nested lists of strings or further nested
lists. The function must test the type of <val>
and return <None> if the type is unknown. The rdump
module will then try other dumper-functions on the
given value.
typename -- the name under which the dumper can later be found,
usually the name of the datatype it dumps.
returns: None if it is a new dumper (new typename) or
the replaced dumper function if a dumper was already
registered under that typename
This is how you add a dumper for your class:
rdump.add_dumper(myclass_dumper)
Here is a complete example:
We define a class T:
>>> class T:
... def __init__(self,x):
... self.x=x
... def __str__(self):
... return "class t with value %s" % self.x
Now we define a special dumper function for T:
>>> def tdump(val,indent,options=default_options):
... if not isinstance(val,T):
... return None
... return str(val)
Here we define a list which contains a "T" object:
>>> a= ["A","B",T(12),"C"]
If we print this list, the unknown "T" object is printed
with the default dumper which looks a bit ugly:
>>> list2str(ldump(a,0)) # doctest: +ELLIPSIS
"[ 'A', 'B', <OBJ: <__main__.T ...>>, 'C' ]"
Now we add our new dumper function to the system:
>>> set_dumper(tdump,"T")
Now we print the list again, now the result looks nicer:
>>> list2str(ldump(a,0))
"[ 'A', 'B', class t with value 12, 'C' ]"
We can also replace a built-in dumper, in this example we show
how the built-in scalar-dumper function
can be replaced.
First we define a new scalar-dumper function:
>>> def new_scalar_dumper(val,indent,options=default_options):
... if not is_scalar(val):
... return None
... return "(new cool dump of %s)" % str(val)
Now we define a simple list:
>>> a=["A","B"]
When we print the list it looks like this:
>>> dump(a)
[ 'A', 'B' ]
Now we replace the old scalar-dumper with the new one. Note that
the old dumper function is stored in the variable "old":
>>> old= set_dumper(new_scalar_dumper,"scalar")
Now, when we print the list, everything looks different:
>>> dump(a,0)
[ (new cool dump of A), (new cool dump of B) ]
Now we install the old scalar-dumper (the replaced function is
returned):
>>> set_dumper(old,"scalar") # doctest: +ELLIPSIS
<function new_scalar_dumper at ...>
And if we print the list again, everything looks like before:
>>> dump(a,0)
[ 'A', 'B' ]
- str_dump_util(mystr, indent, options=None)
- utility to dump a scalar value.
parameters:
mystr -- the string to dump
indent -- the indentation level of each new started line
options -- the options object, see "class options"
The function returns a list which contains
the given string and an optional indent string.
Here are some examples:
>>> str_dump_util("ABC",6,Options(format=REPR,start=False))
['ABC']
>>> str_dump_util("ABC",6,Options(format=STR_D,start=False))
['ABC']
>>> str_dump_util("ABC",6,Options(format=STR,start=False))
['\n', ' ', 'ABC']
>>> str_dump_util("ABC",6,Options(format=STR,start=True))
[' ', 'ABC']
|