# Introduction
Do you ever use `print()` or `log()` to debug your code? If so, ycecream, or `y` for short, will make printing debug information a lot sweeter.
And on top of that, you get some basic benchmarking functionality.
# Installation
Installing ycecream with pip is easy.
```
$ pip install ycecream
```
or when you want to upgrade,
```
$ pip install ycecream --upgrade
```
Alternatively, ycecream.py can be juist copied into you current work directory from GitHub (https://github.com/salabim/ycecream).
No dependencies!
# Inspect variables and expressions
Have you ever printed variables or expressions to debug your program? If you've
ever typed something like
```
print(add2(1000))
```
or the more thorough
```
print("add2(1000)", add2(1000)))
```
or (for Python >= 3.8 only):
```
print(f"{add2(1000) =}")
```
then `y()` is here to help. With arguments, `y()` inspects itself and prints
both its own arguments and the values of those arguments.
```
from ycecream import y
def add2(i):
return i + 2
y(add2(1000))
```
prints
```
y| add2(1000): 1002
```
Similarly,
```
from ycecream import y
class X:
a = 3
world = {"EN": "world", "NL": "wereld", "FR": "monde", "DE": "Welt"}
y(world, X.a)
```
prints
```
y| world: {"EN": "world", "NL": "wereld", "FR": "monde", "DE": "Welt"}, X.a: 3
```
Just give `y()` a variable or expression and you're done. Sweet, isn't it?
# Inspect execution
Have you ever used `print()` to determine which parts of your program are
executed, and in which order they're executed? For example, if you've ever added
print statements to debug code like
```
def add2(i):
print("enter")
result = i + 2
print("exit")
return result
```
then `y()` helps here, too. Without arguments, `y()` inspects itself and
prints the calling line number and -if applicable- the file name and parent function.
```
from ycecream import y
def add2(i):
y()
result = i + 2
y()
return result
y(add2(1000))
```
prints something like
```
y| #3 in add2()
y| #5 in add2()
y| add2(1000): 1002
```
Just call `y()` and you're done. Isn't that sweet?
# Return Value
`y()` returns its argument(s), so `y()` can easily be inserted into
pre-existing code.
```
from ycecream import y
def add2(i):
return i + 2
b = y(add2(1000))
y(b)
```
prints
```
y| add2(1000): 1002
y| b: 1002
```
# Debug entry and exit of function calls
When you apply `y()` as a decorator to a function or method, both the entry and exit can be tracked.
The (keyword) arguments passed will be shown and upon return, the return value.
```
from ycecream import y
@y()
def mul(x, y):
return x * y
print(mul(5, 7))
```
prints
```
y| called mul(5, 7)
y| returned 35 from mul(5, 7) in 0.000006 seconds
35
```
It is possible to suppress the print-out of either the enter or the exit information with
the show_enter and show_exit parameters, like:
```
from ycecream import y
@y(show_exit=False)
def mul(x, y):
return x * y
print(mul(5, 7))
```
prints
```
y| called mul(5, 7)
35
```
Note that it is possible to use `y` as a decorator without the parentheses, like
```
@y
def diode(x):
return 0 if x<0 else x
```
, but this might not work correctly when the def/class definition spawns more than one line. So, always use `y()` or
`y(<parameters>)` when used as a decorator.
# Benchmarking with ycecream
If you decorate a function or method with y, you will be offered the duration between entry and exit (in seconds) as a bonus.
That opens the door to simple benchmarking, like:
```
from ycecream import y
import time
@y(show_enter=False,show_line_number=True)
def do_sort(i):
n = 10 ** i
x = sorted(list(range(n)))
return f"{n:9d}"
for i in range(8):
do_sort(i)
```
the ouput will show the effects of the population size on the sort speed:
```
y| #5 ==> returned ' 1' from do_sort(0) in 0.000027 seconds
y| #5 ==> returned ' 10' from do_sort(1) in 0.000060 seconds
y| #5 ==> returned ' 100' from do_sort(2) in 0.000748 seconds
y| #5 ==> returned ' 1000' from do_sort(3) in 0.001897 seconds
y| #5 ==> returned ' 10000' from do_sort(4) in 0.002231 seconds
y| #5 ==> returned ' 100000' from do_sort(5) in 0.024014 seconds
y| #5 ==> returned ' 1000000' from do_sort(6) in 0.257504 seconds
y| #5 ==> returned ' 10000000' from do_sort(7) in 1.553495 seconds
```
It is also possible to time any code by using y as a context manager, e.g.
```
with y():
time.sleep(1)
```
wil print something like
```
y| enter
y| exit in 1.000900 seconds
```
You can include parameters here as well:
```
with y(show_context=True, show_time=True):
time.sleep(1)
```
will print somethink like:
```
y| #8 @ 13:20:32.605903 ==> enter
y| #8 @ 13:20:33.609519 ==> exit in 1.003358 seconds
```
Finally, to help with timing code, you can request the current delta with
```
y().delta
```
or (re)set it with
```
y().delta = 0
```
So, e.g. to time a section of code:
```
y.delta = 0
time.sleep(1)
duration = y.delta
y(duration)
```
might print:
```
y| duration: 1.0001721999999997
```
# Configuration
For the configuration, it is important to realize that `y` is an instance of the `ycecream._Y` class, which has
a number of configuration attributes:
```
------------------------------------------------------
attribute alternative default
------------------------------------------------------
prefix p "y| "
output o "stderr"
serialize pprint.pformat
show_line_number sln False
show_time st False
show_delta sd False
show_enter se True
show_exit sx True
show_traceback stb False
sort_dicts *) sdi False
enabled e True
line_length ll 80
compact *) c False
indent i 1
depth de 1000000
wrap_indent wi " "
separator sep ", "
context_separator cs " ==> "
equals_separator es ": "
values_only vo False
value_only_for_fstrings voff False
return_none rn False
enforce_line_length ell False
decorator d False
context_manager cm False
delta dl 0
------------------------------------------------------
*) ignored under Python 2.7
```
It is perfectly ok to set/get any of these attributes directly, like
```
y.prefix = "==> "
print(y.prefix)
```
But, it is also possible to apply configuration directly in the call to `y`:
So, it is possible to say
```
from ycecream import y
y(12, prefix="==> ")
```
, which will print
```
==> 12
```
It is also possible to configure y permanently with the configure method.
```
y.configure(prefix="==> ")
y(12)
```
will print
```
==> 12
```
It is arguably easier to say:
```
y.prefix = "==> "
y(12)
```
or even
```
y.p = "==> "
y(12)
```
to print
```
==> 12
```
Yet another way to configure y is to get a new instance of y with y.new() and the required configuration:
```
z = y.new(prefix="==> ")
z(12)
```
will print
```
==> 12
```
Or, yet another possibility is to clone y (optionally with modified attributes):
```
yd1 = y.clone(show_date=True)
yd2 = y.clone()
yd2.configure(show_date=True)
```
After this `yd1` and `yd2` will behave similarly (but they are not the same!)
## prefix / p
```
from ycecream import y
y('world', prefix='hello -> ')
```
prints
```
hello -> 'world'
```
`prefix` can be a function, too.
```
import time
from ycecream import y
def unix_timestamp():
return f"{int(time.time())} "
hello = "world"
y.configure(prefix=unix_timestamp)
y(hello)
```
prints
```
1613635601 hello: 'world'
```
## output / o
This will allow the output to be handled by something else than the default (output being written to stderr).
The `output` attribute can be
* a callable that accepts at least one parameter (the text to be printed)
* a string or Path object that will be used as the filename
* a text file that is open for writing/appending
In the example below,
```
from ycecream import y
import sys
y(1, output=print)
y(2, output=sys.stdout
with open("test", "a+") as f:
y(3, output=f)
y(4, output="")
```
* `y| 1` will be printed to stdout
* `y| 2` will be printed to stdout
* `y| 3` will be appended to the file test
* `y| 4` will *disappear*
As `output` may be any callable, you can even use this to automatically log any `y` output:
```
from ycecream import y
import logging
logging.basicConfig(level="INFO")
log = logging.getLogger("demo")
y.configure(output=log.info)
a = {1, 2, 3, 4, 5}
y(a)
a.remove(4)
y(a)
```
will print to stderr:
```
INFO:demo:y| a: {1, 2, 3, 4, 5}
INFO:demo:y| a: {1, 2, 3, 5}
```
Finally, you can specify the following strings:
```
"stderr" to print to stderr
"stdout" to print to stdout
"null" or "" to completely ignore (dummy) output
"logging.debug" to use logging.debug
"logging.info" to use logging.info
"logging.warning" to use logging.warning
"logging.error" to use logging.error
"logging.critical" to use logging.critical
```
E.g.
```
from ycecream import y
import sys
y.configure(output="stdout")
```
to print to stdout.
## serialize
This will allow to specify how argument values are to be
serialized to displayable strings. The default is pformat (from pprint), but this can be changed to,
for example, to handle non-standard datatypes in a custom fashion.
The serialize function should accept at least one parameter.
The function can optionally accept the keyword arguments `width` and `sort_dicts`, `compact`, `indent` and `depth`.
```
from ycecream import y
def add_len(obj):
if hasattr(obj, "__len__"):
add = f" [len={len(obj)}]"
else:
add = ""
return f"{repr(obj)}{add}"
l = list(range(7))
hello = "world"
y(7, hello, l, serialize=add_len)
```
prints
```
y| 7, hello: 'world' [len=5], l: [0, 1, 2, 3, 4, 5, 6] [len=7]
```
## show_line_number / sln
If True, adds the `y()` call's line number and possible the filename and parent function to `y()`'s output.
```
from ycecream import y
y.configure(show_line_number=True)
def shout():
hello="world"
y(hello)
shout()
```
prints something like
```
y| #5 in shout() ==> hello: 'world'
```
If "no parent" or "n", the parent function will not be shown.
```
from ycecream import y
y.configure(show_line_number="n")
def shout():
hello="world"
y(hello)
shout()
```
prints something like
```
y| #5 ==> hello: 'world'
```
Note that if you call `y` without any arguments, the line number is always shown, regardless of the status `show_line_number`.
See below for an explanation of the information provided.
## show_time / st
If True, adds the current time to `y()`'s output.
```
from ycecream import y
y.configure(show_time=True)
hello="world"
y(hello)
```
prints something like
```
y| @ 13:01:47.588125 ==> hello: 'world'
```
## show_delta / sd
If True, adds the number of seconds since the start of the program to `y()`'s output.
```
from ycecream import y
import time
y.configure(show_delta=True)
french = "bonjour le monde"
english = "hallo world"
y(english)
time.sleep(1)
y(french)
```
prints something like
```
y| delta=0.088 ==> english: 'hallo world'
y| delta=1.091 ==> french: 'bonjour le monde'
```
## show_enter / se
When used as a decorator or context manager, by default, ycecream ouputs a line when the decorated the
function is called or the context manager is entered.
With `show_enter=False` this line can be suppressed.
## show_exit / sx
When used as a decorator or context manager, by default, ycecream ouputs a line when the decorated the
function returned or the context manager is exited.
With `show_exit=False` this line can be suppressed.
## show_traceback / stb
When show_traceback is True, the ordinary output of y() will be followed by a printout of the
traceback, similar to an error traceback.
```
from ycecream import y
y.show_traceback=True
def x():
y()
x()
x()
```
prints
```
y| #4 in x()
Traceback (most recent call last)
File "c:\Users\Ruud\Dropbox (Personal)\Apps\Python Ruud\ycecream\x.py", line 6, in <module>
x()
File "c:\Users\Ruud\Dropbox (Personal)\Apps\Python Ruud\ycecream\x.py", line 4, in x
y()
y| #4 in x()
Traceback (most recent call last)
File "c:\Users\Ruud\Dropbox (Personal)\Apps\Python Ruud\ycecream\x.py", line 7, in <module>
x()
File "c:\Users\Ruud\Dropbox (Personal)\Apps\Python Ruud\ycecream\x.py", line 4, in x
y()
```
The `show_traceback` functionality is also available when y is used as a decorator or context manager.
## line_length / ll
This attribute is used to specify the line length (for wrapping). The default is 80.
Ycecream always tries to keep all output on one line, but if it can't it will wrap:
```
d = dict(a1=1,a2=dict(a=1,b=1,c=3),a3=list(range(10)))
y(d)
y(d, line_length=120)
```
prints
```
y|
d:
{'a1': 1,
'a2': {'a': 1, 'b': 1, 'c': 3},
'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}
y| d: {'a1': 1, 'a2': {'a': 1, 'b': 1, 'c': 3}, 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}
```
## compact / c
This attribute is used to specify the compact parameter for `pformat` (see the pprint documentation
for details). `compact` is False by default.
```
a = 9 * ["0123456789"]
y(a)
y(a, compact=True)
```
prints
```
y|
a:
['0123456789',
'0123456789',
'0123456789',
'0123456789',
'0123456789',
'0123456789',
'0123456789',
'0123456789',
'0123456789']
y|
a:
['0123456789', '0123456789', '0123456789', '0123456789', '0123456789',
'0123456789', '0123456789', '0123456789', '0123456789']
```
Note that `compact` is ignored under Python 2.7.
## indent / i
This attribute is used to specify the indent parameter for `pformat` (see the pprint documentation
for details). `indent` is 1 by default.
```
s = "01234567890012345678900123456789001234567890"
y( [s, [s]])
y( [s, [s]], indent=4)
```
prints
```
y|
[s, [s]]:
['01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890']]
y|
[s, [s]]:
[ '01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890']]
```
## depth / de
This attribute is used to specify the depth parameter for `pformat` (see the pprint documentation
for details). `depth` is `1000000` by default.
```
s = "01234567890012345678900123456789001234567890"
y([s,[s,[s,[s,s]]]])
y([s,[s,[s,[s,s]]]], depth=3)
```
prints
```
y|
[s,[s,[s,[s,s]]]]:
['01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890',
'01234567890012345678900123456789001234567890']]]]
y|
[s,[s,[s,[s,s]]]]:
['01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890',
['01234567890012345678900123456789001234567890', [...]]]]
```
## wrap_indent / wi
This specifies the indent string if the output does not fit in the line_length (has to be wrapped).
Rather than a string, wrap_indent can be also be an integer, in which case the wrap_indent will be that amount of blanks.
The default is 4 blanks.
E.g.
```
d = dict(a1=1,a2=dict(a=1,b=1,c=3),a3=list(range(10)))
y(d, wrap_indent=" ")
y(d, wrap_indent="....")
y(d, wrap_indent=2)
```
prints
```
y|
d:
{'a1': 1,
'a2': {'a': 1, 'b': 1, 'c': 3},
'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}
y|
....d:
........{'a1': 1,
........ 'a2': {'a': 1, 'b': 1, 'c': 3},
........ 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}
y|
d:
{'a1': 1,
'a2': {'a': 1, 'b': 1, 'c': 3},
'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}
```
## enabled / e
Can be used to disable the output:
```
from ycecream import y
y.configure(enabled=False)
s = 'the world is '
y(s + 'perfect.')
y.configure(enabled=True)
y(s + 'on fire.')
```
prints
```
y| s + 'on fire.': 'the world is on fire.'
```
and nothing about a perfect world.
## sort_dicts / sdi
By default, ycecream does not sort dicts (printed by pprint). However, it is possible to get the
default pprint behaviour (i.e. sorting dicts) with the sorted_dicts attribute:
```
world = {"EN": "world", "NL": "wereld", "FR": "monde", "DE": "Welt"}
y(world))
s1 = y(world, sort_dicts=False)
s2 = y(world, sort_dicts=True)
```
prints
```
y| world: {'EN': 'world', 'NL': 'wereld', 'FR': 'monde', 'DE': 'Welt'}
y| world: {'EN': 'world', 'NL': 'wereld', 'FR': 'monde', 'DE': 'Welt'}
y| world: {'DE': 'Welt', 'EN': 'world', 'FR': 'monde', 'NL': 'wereld'}
```
Note that `sort_dicts` is ignored under Python 2.7, i.e. dicts are always sorted.
## separator / sep
By default, pairs (on one line) are separated by `, `.
It is possible to change this with the attribute ` separator`:
```
a="abcd"
b=1
c=1000
d=list("ycecream")
y(a,(b,c),d)
y(a,(b,c),d, separator=" | ")
```
prints
```
y| a: 'abcd', (b,c): (1, 1000), d: ['y', 'c', 'e', 'c', 'r', 'e', 'a', 'm']
y| a: 'abcd' | (b,c): (1, 1000) | d: ['y', 'c', 'e', 'c', 'r', 'e', 'a', 'm']
```
## context_separator / cs
By default the line_number, time and/or delta are followed by ` ==> `.
It is possible to change this with the attribute `context_separator`:
```
a="abcd"
y(a)
y(a, show_time=True, context_separator = ' \u279c ')
```
prints:
```
y| @ 12:56:11.341650 ==> a: 'abcd'
y| @ 12:56:11.485567 ➜ a: 'abcd'
```
## equals_separator / es
By default name of a variable and its value are separated by `: `.
It is possible to change this with the attribute `equals_separator`:
```
a="abcd"
y(a)
y(a, equals_separator = ' == ")
```
prints:
```
y| a: 'abcd'
y| a == 'abcd'
```
## values_only / vo
If False (the default), both the left-hand side (if possible) and the
value will be printed. If True, the left_hand side will be suppressed:
```
hello = "world"
y(hello, 2 * hello)
y(hello, 2 * hello, values_only=True)
```
prints
```
y| hello: 'world', 2 * hello = 'worldworld'
y| 'world', 'worldworld'
```
The values=True version of y can be seen as a supercharged print/pprint.
## values_only_for_fstrings / voff
If False (the default), both the original f-string and the
value will be printed for f-strings.
If True, the left_hand side will be suppressed in case of an f-string:
```
x = 12.3
y(f"{x:0.3e}")
y.values_only_for_fstrings = True
y(f"{x:0.3e}")
```
prints
```
y| f"{x:0.3e}": '1.230e+01'
y| '1.230e+01'
```
Note that if `values_only` is True, f-string will be suppressed, regardless of `values_only_for_fstrings`.
## return_none / rn
Normally, `y()`returns the values passed directly, which is usually fine. However, when used in a notebook
or REPL, that value will be shown, and that can be annoying. Therefore, if `return_none`is True, `y()`will
return None and thus not show anything.
```
a = 3
print(y(a, a + 1))
y.configure(return_none=True)
print(y(a, a + 1))
```
prints
```
y| (3, 4)
(3, 4)
y| (3, 4)
None
```
## enforce_line_length / ell
If enforce_line_length is True, all output lines are explicitely truncated to the given
line_length, even those that are not truncated by pformat.
## delta / dl
The delta attribute can be used to (re)set the current delta, e.g.
```
y.configure(dl=0)
print(y.delta)
```
prints a value that slightly more than 0.
## decorator / d
Normally, an ycecream instance can be used as to show values, as a decorator and as a
context manager.
However, when used from a REPL the usage as a decorator can't be detected properly and in that case,
specify `decorator=True`. E.g.
```
>>>@y(decorator=True)
>>>def add2(x):
>>> return x + 2
>>>print(add2(10))
y| called add2(10)
y| returned 12 from add2(10) in 0.000548 seconds
12
```
The `decorator` attribute is also required when using `y()` as a decorator
witb *fast disabling* (see below).
```
y.enabled([])
@y()
def add2(x):
return x + 2
```
would fail with`TypeError: 'NoneType' object is not callable`, but
```
y.enabled([])
@y(decorator=True)
def add2(x):
return x + 2
```
will run correctly.
## context_manager / cm
Normally, an ycecream instance can be used as to show values, as a decorator and as a
context manager.
However, when used from a REPL the usage as a context manager can't be detected properly and in that case,
specify `context_manager=True`. E.g.
```
>>>with y(context_manager=True)
>>> pass
y| enter
y| exit in 0.008644 seconds
```
The `context_manager` attribute is also required when using `y():` as a context manager
with *fast disabling* (see below).
```
y.enabled([])
with y:
pass
```
would fail with `AttributeError: __enter__`, but
```
y.enabled([])
with y(context_manager=True):
pass
```
will run correctly.
## provided / pr
If provided is False, all output for this call will be suppressed.
If provided is True, output will be generated as usual (obeying the enabled attribute).
```
x = 1
y("should print", provided=x > 0)
y("should not print", provided=x < 0)
```
This will print
```
should print
```
# Return a string instead of sending to output
`y(*args, as_str=True)` is like `y(*args)` but the output is returned as a string instead
of written to output.
```
from ycecream import y
hello = "world"
s = y(hello, as_str=True)
print(s, end="")
```
prints
```
y| hello: 'world'
```
Note that if enabled=False, the call will return the null string (`""`).
# Disabling ycecream's output
```
from ycecream import y
yd = y.fork(show_delta=True)
y(1)
yd(2)
y.enabled = False
y(3)
yd(4)
y.enabled = True
y(5)
yd(6)
print(y.enabled)
```
prints
```
y| 1
y| delta=0.011826 ==> 2
y| 5
y| delta=0.044893 ==> 6
True
```
Of course `y()` continues to return its arguments when disabled, of course.
It is also possible to suppress output with the provided attribute (see above).
## Speeding up disabled ycecream
When output is disabled, either via `y.configure(enbabled=False)` or `ycecream.enable = False`,
ycecream still has to check for usage as a decorator or context manager, which can be rather time
consuming.
In order to speed up a program with disabled ycecream calls, it is possible to specify
`y.configure(enabled=[])`, in which case `y` will always just return
the given arguments. If ycecream is disabled this way, usage as a `@y()` decorator or as a `with y():`
context manager will raise a runtime error, though. The `@y` decorator without parentheses will
not raise any exception, though.
To use `y` as a decorator and still have *fast disabling*:
```
y.configure(enabled=[])
@y(decorator=True):
def add2(x):
return x + 2
x34 = add2(30)
```
And, similarly, to use `y` as a context manager combined with *fast disabling*:
```
y.configure(enabled=[])
with @y(context_manager=True):
pass
```
The table below shows it all.
```
-------------------------------------------------------------------------------
enabled=True enabled=False enabled=[]
-------------------------------------------------------------------------------
execution speed normal normal fast
y() normal no output no output
@y normal no output no output
y(decorator=True) normal no output no output
y(context_manager=True) normal no output no output
@y() normal no output TypeError
with y(): normal no output AttributeError/TypeError
y(as_str=True) normal "" ""
-------------------------------------------------------------------------------
```
# Using ycecream as a substitute for `assert`
Ycecream has a method `assert_` that works like `assert`, but can be enabled or disabled with the enabled flag.
```
temperature = -1
y.assert_(temperature > 0)
```
This will raise an AttributeError.
But
```
y.enabled = False
temperature = -1
y.assert_(temperature > 0)
```
will not.
Note that with the attribute propagation method, you can in effect have a layered assert system.
# Interpreting the line number information
When `show_line_number` is True or y() is used without any parameters, the output will contain the line number like:
```
y| #3 ==> a: 'abcd'
```
If the line resides in another file than the main file, the filename (without the path) will be shown as well:
```
y| #30[foo.py] ==> foo: 'Foo'
```
And finally when used in a function or method, that function/method will be shown as well:
```
y| #456[foo.py] in square_root ==> x: 123
```
The parent function can be suppressed by setting `show_line_number` or `sln` to `"n"` or `"no parent"`.
# Configuring at import time
It can be useful to configure ycecream at import time. This can be done by providing a `ycecream.json` file which
can contain any attribute configuration overriding the standard settings.
E.g. if there is an `ycecream.json` file with the following contents
```
{
"o": "stdout",
"show_time": true,
"line_length": 120`
'compact' : true
}
```
in the same folder as the application, this program:
```
from ycecream import y
hello = "world"
y(hello)
```
will print to stdout (rather than stderr):
```
y| @ 14:53:41.392190 ==> hello: 'world'
```
At import time the sys.path will be searched for, in that order, to find an `ycecream.json` file and use that. This mean that
you can place an `ycecream.json` file in the site-packages folder where `ycecream` is installed to always use
these modified settings.
Please observe that json values are slightly different from their Python equivalents:
```
-------------------------------
Python json
-------------------------------
True true
False false
None none
strings always double quoted
-------------------------------
```
Note that not-specified attributes will remain the default settings.
For obvious reasons, it is not possible to specify `serialize` in an ycecream.json file.
# Working with multiple instances of y
Normally, only the `y()` object is used.
It can be useful to have multiple instances, e.g. when some of the debugging has to be done with context information
and others requires an alternative prefix.
THere are several ways to obtain a new instance of ycecream:
* by using `y.new()`
With this a new ycecream object is created with the default attributes
and possibly ycecream.json overrides.
* by using `y.new(ignore_json=True)`
With this a new ycecreamobject is created with the default attibutes. Any ycecream.json files asre ignored.
* by using `y.fork()`
With this a new ycecream object is created with the same attributes as the object it is created ('the parent') from. Note that any non set attributes are copied (propagated) from the parent.
* by using `y.clone()`, which copies all attributes from y()
With this a new ycecream object is created with the same attributes as the object it is created ('the parent') from. Note that the attributes are not propagated from the parent, in this case.
* with `y()` used as a context manager
In either case, attributes can be added to override the default ones.
### Example
```
from ycecream import y
y_with_line_number = y.fork(show_line_number=True)
y_with_new_prefix = y.new(prefix="==> ")
y_with_new_prefix_and_time = y_with_new_prefix.clone(show_time=True)
hello="world"
y_with_line_number(hello)
y_with_new_prefix(hello)
y_with_new_prefix_and_time(hello)
y.equals_separator = " == " # this affects only the forked objects
y_with_line_number(hello)
y_with_new_prefix(hello)
y_with_new_prefix_and_time(hello)
with y(prefix="ycm ") as ycm:
ycm(hello)
y(hello)
```
prints
```
y| #6 ==> hello: 'world'
==> hello: 'world'
==> @ 09:55:10.883732 ==> hello: 'world'
y| #10 ==> hello == 'world'
==> hello: 'world'
==> @ 09:55:10.910717 ==> hello: 'world'
ycm enter
ycm hello == 'world'
y| hello == 'world'
ycm exit in 0.017686 seconds
```
## ignore_json
With `y.new(ignore_json=True)` an instance of y without having applied any json configuration file will be returned. That can be useful when guaranteeing the same output in several setups.
### Example
Suppose we have an `ycecream.json` file in the current directory with the contents
```
{prefix="==>"}
```
Then
```
y_post_json = y.new()
y_ignore_json = y.new(ignore_json=True)
hello = "world"
y(hello)
y_post_json(hello)
y_ignore_json(hello)
```
prints
```
==>hello: 'world'
==>hello: 'world'
y| hello: 'world'
```
# Test script
On GitHub is a file `test_ycecream.py` that tests (and thus also demonstrates) most of the functionality
of ycecream.
It is very useful to have a look at the tests to see the features (some may be not covered (yet) in this readme).
# Using ycecream in a REPL
Ycecream may be used in a REPL, but with limited functionality:
* all arguments are just presented as such, i.e. no left-hand side, e.g.
```
>> hello = "world"
>>> y(hello, hello * 2)
y| 'hello', 'hellohello'
('hello', 'hellohello')
```
* line numbers are never shown
* use as a decorator is only supported when you used as `y(decorator=True)` or `y(d=1)`
* use as a context manager is only supported when used as `y(context_manager=True)`or `y(cm=1)`
# Alternative to `y`
Sometimes, it is not suitable to use the name y in a program, e.g. when
dealing with coordinates x, y and z.
In that case, it is possible to use yc instead
```
from ycecream import yc
```
The `yc` object is a *fork* of y with the prefix `"yc| "`. That means that attributes of `y` are propagated to `yc`, unless overridden.
Of course, it is also possible to use
```
from ycecream import y as yy
```
or
```
yy = y.new()
```
or
```
yy = y.new(prefix="yy| ")
```
# Alternative installation
With `install ycecream from github.py`, you can install the ycecream.py directly from GitHub to the site packages (as if it was a pip install).
With `install ycecream.py`, you can install the ycecream.py in your current directory to the site packages (as if it was a pip install).
Both files can be found in the GitHub repository (https://github.com/salabim/ycecream).
# Limitations
It is not possible to use ycecream:
* from a frozen application (e.g. packaged with PyInstaller)
* when the underlying source code has changed during execution
# Implementation details
Although not important for using the package, here are some implementation details:
* ycecream.py contains the complete source of the asttokens and executing packages, in
order to offer the required source lookups, without any dependencies
* ycecream.py contains the complete source of pprint as of Python 3.8 in order to support the sort_dicts parameter, Under Python 2.7 this is ignored and the pprint module
from the standard library is used.
* in order to support using y() as a decorator and a context manager, ycecream caches the complete source of
any source file that uses y()
# Acknowledgement
The **ycecream** pacakage is inspired by the **IceCream** package, but is a
nearly complete rewrite. See https://github.com/gruns/icecream
Many thanks to the author Ansgar Grunseid / grunseid.com / grunseid@gmail.com .
# Differences with IceCream
The ycecream module was originally a fork of IceCream, but has many differences:
```
----------------------------------------------------------------------------------------
characteristic ycecream IceCream
----------------------------------------------------------------------------------------
platform Python 2.7, >=3.6, PyPy Python 2.7, >=3.5, PyPy
default name y (or yc) ic
dependencies none many
number of files 1 several
usable without installation yes no
can be used as a decorator yes no
can be used as a context manager yes no
can show traceback yes no
PEP8 (Pythonic) API yes no
sorts dicts no by default, optional yes
supports compact, indent and
depth parameters of pprint yes no
use from a REPL limited functionality no
external configuration via json file no
observes line_length correctly yes no
benchmarking functionality yes no
suppress f-strings at left hand optional no
indentation 4 blanks (overridable) dependent on length of prefix
forking and cloning yes no
test script pytest unittest
colourize no yes (can be disabled)
----------------------------------------------------------------------------------------
*) sort_dicts and compact are ignored under Python 2.7
Raw data
{
"_id": null,
"home_page": "https://github.com/salabim/ycecream",
"name": "ycecream",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "debugging,utility,tool,benchmarking",
"author": "Ruud van der Ham",
"author_email": "info@salabim.org",
"download_url": "https://files.pythonhosted.org/packages/09/8f/076cab3636e474d5ae21b4e917f632ad5fd2f654d178699aab2ff986d0a3/ycecream-1.3.17.tar.gz",
"platform": null,
"description": "# Introduction\r\n\r\nDo you ever use `print()` or `log()` to debug your code? If so, ycecream, or `y` for short, will make printing debug information a lot sweeter.\r\nAnd on top of that, you get some basic benchmarking functionality.\r\n\r\n# Installation\r\n\r\nInstalling ycecream with pip is easy.\r\n```\r\n$ pip install ycecream\r\n```\r\nor when you want to upgrade,\r\n```\r\n$ pip install ycecream --upgrade\r\n```\r\n\r\nAlternatively, ycecream.py can be juist copied into you current work directory from GitHub (https://github.com/salabim/ycecream).\r\n\r\nNo dependencies!\r\n\r\n\r\n# Inspect variables and expressions\r\n\r\nHave you ever printed variables or expressions to debug your program? If you've\r\never typed something like\r\n\r\n```\r\nprint(add2(1000))\r\n```\r\n\r\nor the more thorough\r\n\r\n```\r\nprint(\"add2(1000)\", add2(1000)))\r\n```\r\nor (for Python >= 3.8 only):\r\n```\r\nprint(f\"{add2(1000) =}\")\r\n```\r\n\r\nthen `y()` is here to help. With arguments, `y()` inspects itself and prints\r\nboth its own arguments and the values of those arguments.\r\n\r\n```\r\nfrom ycecream import y\r\n\r\ndef add2(i):\r\n return i + 2\r\n\r\ny(add2(1000))\r\n```\r\n\r\nprints\r\n```\r\ny| add2(1000): 1002\r\n```\r\n\r\nSimilarly,\r\n\r\n```\r\nfrom ycecream import y\r\nclass X:\r\n a = 3\r\nworld = {\"EN\": \"world\", \"NL\": \"wereld\", \"FR\": \"monde\", \"DE\": \"Welt\"}\r\n\r\ny(world, X.a)\r\n```\r\n\r\nprints\r\n```\r\ny| world: {\"EN\": \"world\", \"NL\": \"wereld\", \"FR\": \"monde\", \"DE\": \"Welt\"}, X.a: 3\r\n```\r\nJust give `y()` a variable or expression and you're done. Sweet, isn't it?\r\n\r\n\r\n# Inspect execution\r\n\r\nHave you ever used `print()` to determine which parts of your program are\r\nexecuted, and in which order they're executed? For example, if you've ever added\r\nprint statements to debug code like\r\n\r\n```\r\ndef add2(i):\r\n print(\"enter\")\r\n result = i + 2\r\n print(\"exit\")\r\n return result\r\n```\r\nthen `y()` helps here, too. Without arguments, `y()` inspects itself and\r\nprints the calling line number and -if applicable- the file name and parent function.\r\n\r\n```\r\nfrom ycecream import y\r\ndef add2(i):\r\n y()\r\n result = i + 2\r\n y()\r\n return result\r\ny(add2(1000))\r\n```\r\n\r\nprints something like\r\n```\r\ny| #3 in add2()\r\ny| #5 in add2()\r\ny| add2(1000): 1002\r\n```\r\nJust call `y()` and you're done. Isn't that sweet?\r\n\r\n\r\n# Return Value\r\n\r\n`y()` returns its argument(s), so `y()` can easily be inserted into\r\npre-existing code.\r\n\r\n```\r\nfrom ycecream import y\r\ndef add2(i):\r\n return i + 2\r\nb = y(add2(1000))\r\ny(b)\r\n```\r\nprints\r\n```\r\ny| add2(1000): 1002\r\ny| b: 1002\r\n```\r\n# Debug entry and exit of function calls\r\n\r\nWhen you apply `y()` as a decorator to a function or method, both the entry and exit can be tracked.\r\nThe (keyword) arguments passed will be shown and upon return, the return value.\r\n\r\n```\r\nfrom ycecream import y\r\n@y()\r\ndef mul(x, y):\r\n return x * y\r\n \r\nprint(mul(5, 7))\r\n```\r\nprints\r\n```\r\ny| called mul(5, 7)\r\ny| returned 35 from mul(5, 7) in 0.000006 seconds\r\n35\r\n```\r\nIt is possible to suppress the print-out of either the enter or the exit information with\r\nthe show_enter and show_exit parameters, like:\r\n\r\n```\r\nfrom ycecream import y\r\n@y(show_exit=False)\r\ndef mul(x, y):\r\n return x * y\r\n \r\nprint(mul(5, 7))\r\n```\r\nprints\r\n```\r\ny| called mul(5, 7)\r\n35\r\n```\r\nNote that it is possible to use `y` as a decorator without the parentheses, like\r\n```\r\n@y\r\ndef diode(x):\r\n return 0 if x<0 else x\r\n```\r\n, but this might not work correctly when the def/class definition spawns more than one line. So, always use `y()` or\r\n`y(<parameters>)` when used as a decorator. \r\n\r\n# Benchmarking with ycecream\r\n\r\nIf you decorate a function or method with y, you will be offered the duration between entry and exit (in seconds) as a bonus.\r\n\r\nThat opens the door to simple benchmarking, like:\r\n```\r\nfrom ycecream import y\r\nimport time\r\n\r\n@y(show_enter=False,show_line_number=True)\r\ndef do_sort(i):\r\n n = 10 ** i\r\n x = sorted(list(range(n)))\r\n return f\"{n:9d}\" \r\n \r\nfor i in range(8):\r\n do_sort(i)\r\n```\r\nthe ouput will show the effects of the population size on the sort speed:\r\n```\r\ny| #5 ==> returned ' 1' from do_sort(0) in 0.000027 seconds\r\ny| #5 ==> returned ' 10' from do_sort(1) in 0.000060 seconds\r\ny| #5 ==> returned ' 100' from do_sort(2) in 0.000748 seconds\r\ny| #5 ==> returned ' 1000' from do_sort(3) in 0.001897 seconds\r\ny| #5 ==> returned ' 10000' from do_sort(4) in 0.002231 seconds\r\ny| #5 ==> returned ' 100000' from do_sort(5) in 0.024014 seconds\r\ny| #5 ==> returned ' 1000000' from do_sort(6) in 0.257504 seconds\r\ny| #5 ==> returned ' 10000000' from do_sort(7) in 1.553495 seconds\r\n```\r\n\r\nIt is also possible to time any code by using y as a context manager, e.g.\r\n```\r\nwith y():\r\n time.sleep(1)\r\n```\r\nwil print something like\r\n```\r\ny| enter\r\ny| exit in 1.000900 seconds\r\n```\r\nYou can include parameters here as well:\r\n```\r\nwith y(show_context=True, show_time=True):\r\n time.sleep(1)\r\n```\r\nwill print somethink like:\r\n```\r\ny| #8 @ 13:20:32.605903 ==> enter\r\ny| #8 @ 13:20:33.609519 ==> exit in 1.003358 seconds\r\n```\r\n\r\nFinally, to help with timing code, you can request the current delta with\r\n```\r\ny().delta\r\n```\r\nor (re)set it with\r\n```\r\ny().delta = 0\r\n```\r\nSo, e.g. to time a section of code:\r\n```\r\ny.delta = 0\r\ntime.sleep(1)\r\nduration = y.delta\r\ny(duration)\r\n```\r\nmight print:\r\n```\r\ny| duration: 1.0001721999999997\r\n```\r\n\r\n# Configuration\r\n\r\nFor the configuration, it is important to realize that `y` is an instance of the `ycecream._Y` class, which has\r\na number of configuration attributes:\r\n```\r\n------------------------------------------------------\r\nattribute alternative default\r\n------------------------------------------------------\r\nprefix p \"y| \"\r\noutput o \"stderr\"\r\nserialize pprint.pformat\r\nshow_line_number sln False\r\nshow_time st False\r\nshow_delta sd False\r\nshow_enter se True\r\nshow_exit sx True\r\nshow_traceback stb False\r\nsort_dicts *) sdi False\r\nenabled e True\r\nline_length ll 80\r\ncompact *) c False\r\nindent i 1\r\ndepth de 1000000\r\nwrap_indent wi \" \" \r\nseparator sep \", \"\r\ncontext_separator cs \" ==> \"\r\nequals_separator es \": \"\r\nvalues_only vo False\r\nvalue_only_for_fstrings voff False \r\nreturn_none rn False\r\nenforce_line_length ell False\r\ndecorator d False\r\ncontext_manager cm False\r\ndelta dl 0\r\n------------------------------------------------------\r\n*) ignored under Python 2.7\r\n```\r\nIt is perfectly ok to set/get any of these attributes directly, like\r\n```\r\ny.prefix = \"==> \"\r\nprint(y.prefix)\r\n```\r\n\r\nBut, it is also possible to apply configuration directly in the call to `y`:\r\nSo, it is possible to say\r\n```\r\nfrom ycecream import y\r\ny(12, prefix=\"==> \")\r\n```\r\n, which will print\r\n```\r\n==> 12\r\n```\r\nIt is also possible to configure y permanently with the configure method. \r\n```\r\ny.configure(prefix=\"==> \")\r\ny(12)\r\n```\r\nwill print\r\n```\r\n==> 12\r\n```\r\nIt is arguably easier to say:\r\n```\r\ny.prefix = \"==> \"\r\ny(12)\r\n```\r\nor even\r\n```\r\ny.p = \"==> \"\r\ny(12)\r\n```\r\nto print\r\n```\r\n==> 12\r\n```\r\nYet another way to configure y is to get a new instance of y with y.new() and the required configuration:\r\n```\r\nz = y.new(prefix=\"==> \")\r\nz(12)\r\n```\r\nwill print\r\n```\r\n==> 12\r\n```\r\n\r\nOr, yet another possibility is to clone y (optionally with modified attributes):\r\n```\r\nyd1 = y.clone(show_date=True)\r\nyd2 = y.clone()\r\nyd2.configure(show_date=True)\r\n```\r\nAfter this `yd1` and `yd2` will behave similarly (but they are not the same!)\r\n\r\n## prefix / p\r\n```\r\nfrom ycecream import y\r\ny('world', prefix='hello -> ')\r\n```\r\nprints\r\n```\r\nhello -> 'world'\r\n```\r\n\r\n`prefix` can be a function, too.\r\n\r\n```\r\nimport time\r\nfrom ycecream import y\r\ndef unix_timestamp():\r\n return f\"{int(time.time())} \"\r\nhello = \"world\"\r\ny.configure(prefix=unix_timestamp)\r\ny(hello) \r\n```\r\nprints\r\n```\r\n1613635601 hello: 'world'\r\n```\r\n\r\n## output / o\r\nThis will allow the output to be handled by something else than the default (output being written to stderr).\r\n\r\nThe `output` attribute can be\r\n\r\n* a callable that accepts at least one parameter (the text to be printed)\r\n* a string or Path object that will be used as the filename\r\n* a text file that is open for writing/appending\r\n\r\nIn the example below, \r\n```\r\nfrom ycecream import y\r\nimport sys\r\ny(1, output=print)\r\ny(2, output=sys.stdout\r\nwith open(\"test\", \"a+\") as f:\r\n y(3, output=f)\r\ny(4, output=\"\")\r\n```\r\n* `y| 1` will be printed to stdout\r\n* `y| 2` will be printed to stdout\r\n* `y| 3` will be appended to the file test\r\n* `y| 4` will *disappear*\r\n\r\nAs `output` may be any callable, you can even use this to automatically log any `y` output:\r\n```\r\nfrom ycecream import y\r\nimport logging\r\nlogging.basicConfig(level=\"INFO\")\r\nlog = logging.getLogger(\"demo\")\r\ny.configure(output=log.info)\r\na = {1, 2, 3, 4, 5}\r\ny(a)\r\na.remove(4)\r\ny(a)\r\n```\r\nwill print to stderr:\r\n```\r\nINFO:demo:y| a: {1, 2, 3, 4, 5}\r\nINFO:demo:y| a: {1, 2, 3, 5}\r\n```\r\nFinally, you can specify the following strings:\r\n```\r\n\"stderr\" to print to stderr\r\n\"stdout\" to print to stdout\r\n\"null\" or \"\" to completely ignore (dummy) output \r\n\"logging.debug\" to use logging.debug\r\n\"logging.info\" to use logging.info\r\n\"logging.warning\" to use logging.warning\r\n\"logging.error\" to use logging.error\r\n\"logging.critical\" to use logging.critical\r\n```\r\nE.g.\r\n```\r\nfrom ycecream import y\r\nimport sys\r\ny.configure(output=\"stdout\")\r\n```\r\nto print to stdout.\r\n\r\n## serialize\r\nThis will allow to specify how argument values are to be\r\nserialized to displayable strings. The default is pformat (from pprint), but this can be changed to,\r\nfor example, to handle non-standard datatypes in a custom fashion.\r\nThe serialize function should accept at least one parameter.\r\nThe function can optionally accept the keyword arguments `width` and `sort_dicts`, `compact`, `indent` and `depth`.\r\n```\r\nfrom ycecream import y\r\ndef add_len(obj):\r\n if hasattr(obj, \"__len__\"):\r\n add = f\" [len={len(obj)}]\"\r\n else:\r\n add = \"\"\r\n return f\"{repr(obj)}{add}\"\r\n\r\nl = list(range(7))\r\nhello = \"world\"\r\ny(7, hello, l, serialize=add_len)\r\n``` \r\nprints\r\n```\r\ny| 7, hello: 'world' [len=5], l: [0, 1, 2, 3, 4, 5, 6] [len=7]\r\n```\r\n\r\n## show_line_number / sln\r\nIf True, adds the `y()` call's line number and possible the filename and parent function to `y()`'s output.\r\n\r\n```\r\nfrom ycecream import y\r\ny.configure(show_line_number=True)\r\ndef shout():\r\n hello=\"world\"\r\n y(hello)\r\nshout()\r\n```\r\nprints something like\r\n```\r\ny| #5 in shout() ==> hello: 'world'\r\n```\r\n\r\nIf \"no parent\" or \"n\", the parent function will not be shown.\r\n```\r\nfrom ycecream import y\r\ny.configure(show_line_number=\"n\")\r\ndef shout():\r\n hello=\"world\"\r\n y(hello)\r\nshout()\r\n```\r\nprints something like\r\n```\r\ny| #5 ==> hello: 'world'\r\n```\r\nNote that if you call `y` without any arguments, the line number is always shown, regardless of the status `show_line_number`.\r\n\r\nSee below for an explanation of the information provided.\r\n\r\n## show_time / st\r\nIf True, adds the current time to `y()`'s output.\r\n\r\n```\r\nfrom ycecream import y\r\ny.configure(show_time=True)\r\nhello=\"world\"\r\ny(hello)\r\n```\r\nprints something like\r\n```\r\ny| @ 13:01:47.588125 ==> hello: 'world'\r\n```\r\n\r\n## show_delta / sd\r\nIf True, adds the number of seconds since the start of the program to `y()`'s output.\r\n```\r\nfrom ycecream import y\r\nimport time\r\ny.configure(show_delta=True)\r\nfrench = \"bonjour le monde\"\r\nenglish = \"hallo world\"\r\ny(english)\r\ntime.sleep(1)\r\ny(french)\r\n```\r\nprints something like\r\n```\r\ny| delta=0.088 ==> english: 'hallo world'\r\ny| delta=1.091 ==> french: 'bonjour le monde'\r\n```\r\n\r\n## show_enter / se\r\nWhen used as a decorator or context manager, by default, ycecream ouputs a line when the decorated the\r\nfunction is called or the context manager is entered.\r\n\r\nWith `show_enter=False` this line can be suppressed.\r\n\r\n## show_exit / sx\r\nWhen used as a decorator or context manager, by default, ycecream ouputs a line when the decorated the\r\nfunction returned or the context manager is exited.\r\n\r\nWith `show_exit=False` this line can be suppressed.\r\n\r\n\r\n## show_traceback / stb\r\nWhen show_traceback is True, the ordinary output of y() will be followed by a printout of the\r\ntraceback, similar to an error traceback.\r\n```\r\nfrom ycecream import y\r\ny.show_traceback=True\r\ndef x():\r\n y()\r\n\r\nx()\r\nx()\r\n```\r\nprints\r\n```\r\ny| #4 in x()\r\n Traceback (most recent call last)\r\n File \"c:\\Users\\Ruud\\Dropbox (Personal)\\Apps\\Python Ruud\\ycecream\\x.py\", line 6, in <module>\r\n x()\r\n File \"c:\\Users\\Ruud\\Dropbox (Personal)\\Apps\\Python Ruud\\ycecream\\x.py\", line 4, in x\r\n y()\r\ny| #4 in x()\r\n Traceback (most recent call last)\r\n File \"c:\\Users\\Ruud\\Dropbox (Personal)\\Apps\\Python Ruud\\ycecream\\x.py\", line 7, in <module>\r\n x()\r\n File \"c:\\Users\\Ruud\\Dropbox (Personal)\\Apps\\Python Ruud\\ycecream\\x.py\", line 4, in x\r\n y()\r\n```\r\nThe `show_traceback` functionality is also available when y is used as a decorator or context manager. \r\n\r\n## line_length / ll\r\nThis attribute is used to specify the line length (for wrapping). The default is 80.\r\nYcecream always tries to keep all output on one line, but if it can't it will wrap:\r\n```\r\nd = dict(a1=1,a2=dict(a=1,b=1,c=3),a3=list(range(10)))\r\ny(d)\r\ny(d, line_length=120)\r\n```\r\nprints\r\n```\r\ny|\r\n d:\r\n {'a1': 1,\r\n 'a2': {'a': 1, 'b': 1, 'c': 3},\r\n 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}\r\ny| d: {'a1': 1, 'a2': {'a': 1, 'b': 1, 'c': 3}, 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}\r\n```\r\n\r\n## compact / c\r\nThis attribute is used to specify the compact parameter for `pformat` (see the pprint documentation\r\nfor details). `compact` is False by default.\r\n```\r\na = 9 * [\"0123456789\"]\r\ny(a)\r\ny(a, compact=True)\r\n```\r\nprints\r\n```\r\ny|\r\n a:\r\n ['0123456789',\r\n '0123456789',\r\n '0123456789',\r\n '0123456789',\r\n '0123456789',\r\n '0123456789',\r\n '0123456789',\r\n '0123456789',\r\n '0123456789']\r\ny|\r\n a:\r\n ['0123456789', '0123456789', '0123456789', '0123456789', '0123456789',\r\n '0123456789', '0123456789', '0123456789', '0123456789']\r\n```\r\nNote that `compact` is ignored under Python 2.7.\r\n\r\n## indent / i\r\nThis attribute is used to specify the indent parameter for `pformat` (see the pprint documentation\r\nfor details). `indent` is 1 by default.\r\n```\r\ns = \"01234567890012345678900123456789001234567890\"\r\ny( [s, [s]])\r\ny( [s, [s]], indent=4)\r\n```\r\nprints\r\n```\r\ny|\r\n [s, [s]]:\r\n ['01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890']]\r\ny|\r\n [s, [s]]:\r\n [ '01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890']]\r\n```\r\n\r\n## depth / de\r\nThis attribute is used to specify the depth parameter for `pformat` (see the pprint documentation\r\nfor details). `depth` is `1000000` by default. \r\n```\r\ns = \"01234567890012345678900123456789001234567890\"\r\ny([s,[s,[s,[s,s]]]])\r\ny([s,[s,[s,[s,s]]]], depth=3)\r\n```\r\nprints\r\n```\r\ny|\r\n [s,[s,[s,[s,s]]]]:\r\n ['01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890',\r\n '01234567890012345678900123456789001234567890']]]]\r\ny|\r\n [s,[s,[s,[s,s]]]]:\r\n ['01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890',\r\n ['01234567890012345678900123456789001234567890', [...]]]]\r\n```\r\n\r\n## wrap_indent / wi\r\nThis specifies the indent string if the output does not fit in the line_length (has to be wrapped).\r\nRather than a string, wrap_indent can be also be an integer, in which case the wrap_indent will be that amount of blanks.\r\nThe default is 4 blanks.\r\n\r\nE.g.\r\n```\r\nd = dict(a1=1,a2=dict(a=1,b=1,c=3),a3=list(range(10)))\r\ny(d, wrap_indent=\" \")\r\ny(d, wrap_indent=\"....\")\r\ny(d, wrap_indent=2)\r\n```\r\nprints\r\n```\r\ny|\r\n d:\r\n {'a1': 1,\r\n 'a2': {'a': 1, 'b': 1, 'c': 3},\r\n 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}\r\ny|\r\n....d:\r\n........{'a1': 1,\r\n........ 'a2': {'a': 1, 'b': 1, 'c': 3},\r\n........ 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}\r\ny|\r\n d:\r\n {'a1': 1,\r\n 'a2': {'a': 1, 'b': 1, 'c': 3},\r\n 'a3': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]}\r\n```\r\n\r\n## enabled / e\r\nCan be used to disable the output:\r\n```\r\nfrom ycecream import y\r\n\r\ny.configure(enabled=False)\r\ns = 'the world is '\r\ny(s + 'perfect.')\r\ny.configure(enabled=True)\r\ny(s + 'on fire.')\r\n```\r\nprints\r\n```\r\ny| s + 'on fire.': 'the world is on fire.'\r\n```\r\nand nothing about a perfect world.\r\n\r\n## sort_dicts / sdi\r\nBy default, ycecream does not sort dicts (printed by pprint). However, it is possible to get the\r\ndefault pprint behaviour (i.e. sorting dicts) with the sorted_dicts attribute:\r\n\r\n```\r\nworld = {\"EN\": \"world\", \"NL\": \"wereld\", \"FR\": \"monde\", \"DE\": \"Welt\"}\r\ny(world))\r\ns1 = y(world, sort_dicts=False)\r\ns2 = y(world, sort_dicts=True)\r\n```\r\nprints\r\n```\r\ny| world: {'EN': 'world', 'NL': 'wereld', 'FR': 'monde', 'DE': 'Welt'}\r\ny| world: {'EN': 'world', 'NL': 'wereld', 'FR': 'monde', 'DE': 'Welt'}\r\ny| world: {'DE': 'Welt', 'EN': 'world', 'FR': 'monde', 'NL': 'wereld'}\r\n```\r\nNote that `sort_dicts` is ignored under Python 2.7, i.e. dicts are always sorted.\r\n\r\n## separator / sep\r\nBy default, pairs (on one line) are separated by `, `.\r\nIt is possible to change this with the attribute ` separator`:\r\n```\r\na=\"abcd\"\r\nb=1\r\nc=1000\r\nd=list(\"ycecream\")\r\ny(a,(b,c),d)\r\ny(a,(b,c),d, separator=\" | \")\r\n```\r\nprints\r\n```\r\ny| a: 'abcd', (b,c): (1, 1000), d: ['y', 'c', 'e', 'c', 'r', 'e', 'a', 'm']\r\ny| a: 'abcd' | (b,c): (1, 1000) | d: ['y', 'c', 'e', 'c', 'r', 'e', 'a', 'm']\r\n```\r\n## context_separator / cs\r\nBy default the line_number, time and/or delta are followed by ` ==> `.\r\nIt is possible to change this with the attribute `context_separator`:\r\n```\r\na=\"abcd\"\r\ny(a)\r\ny(a, show_time=True, context_separator = ' \\u279c ')\r\n```\r\nprints:\r\n```\r\ny| @ 12:56:11.341650 ==> a: 'abcd'\r\ny| @ 12:56:11.485567 \u279c a: 'abcd'\r\n```\r\n## equals_separator / es\r\nBy default name of a variable and its value are separated by `: `.\r\nIt is possible to change this with the attribute `equals_separator`:\r\n```\r\na=\"abcd\"\r\ny(a)\r\ny(a, equals_separator = ' == \")\r\n```\r\nprints:\r\n```\r\ny| a: 'abcd'\r\ny| a == 'abcd'\r\n```\r\n\r\n## values_only / vo\r\nIf False (the default), both the left-hand side (if possible) and the\r\nvalue will be printed. If True, the left_hand side will be suppressed:\r\n```\r\nhello = \"world\"\r\ny(hello, 2 * hello)\r\ny(hello, 2 * hello, values_only=True)\r\n```\r\nprints\r\n```\r\ny| hello: 'world', 2 * hello = 'worldworld'\r\ny| 'world', 'worldworld'\r\n```\r\nThe values=True version of y can be seen as a supercharged print/pprint.\r\n\r\n\r\n## values_only_for_fstrings / voff\r\nIf False (the default), both the original f-string and the\r\nvalue will be printed for f-strings.\r\nIf True, the left_hand side will be suppressed in case of an f-string:\r\n```\r\nx = 12.3\r\ny(f\"{x:0.3e}\")\r\ny.values_only_for_fstrings = True\r\ny(f\"{x:0.3e}\")\r\n```\r\nprints\r\n```\r\ny| f\"{x:0.3e}\": '1.230e+01'\r\ny| '1.230e+01'\r\n```\r\nNote that if `values_only` is True, f-string will be suppressed, regardless of `values_only_for_fstrings`.\r\n\r\n## return_none / rn\r\nNormally, `y()`returns the values passed directly, which is usually fine. However, when used in a notebook\r\nor REPL, that value will be shown, and that can be annoying. Therefore, if `return_none`is True, `y()`will\r\nreturn None and thus not show anything.\r\n```\r\na = 3\r\nprint(y(a, a + 1))\r\ny.configure(return_none=True)\r\nprint(y(a, a + 1))\r\n```\r\nprints\r\n```\r\ny| (3, 4)\r\n(3, 4)\r\ny| (3, 4)\r\nNone\r\n```\r\n\r\n## enforce_line_length / ell\r\nIf enforce_line_length is True, all output lines are explicitely truncated to the given\r\nline_length, even those that are not truncated by pformat.\r\n\r\n## delta / dl\r\nThe delta attribute can be used to (re)set the current delta, e.g.\r\n```\r\ny.configure(dl=0)\r\nprint(y.delta)\r\n```\r\nprints a value that slightly more than 0.\r\n\r\n\r\n## decorator / d\r\nNormally, an ycecream instance can be used as to show values, as a decorator and as a\r\ncontext manager.\r\n\r\nHowever, when used from a REPL the usage as a decorator can't be detected properly and in that case,\r\nspecify `decorator=True`. E.g. \r\n```\r\n>>>@y(decorator=True)\r\n>>>def add2(x):\r\n>>> return x + 2\r\n>>>print(add2(10))\r\ny| called add2(10)\r\ny| returned 12 from add2(10) in 0.000548 seconds\r\n12\r\n```\r\n\r\nThe `decorator` attribute is also required when using `y()` as a decorator\r\nwitb *fast disabling* (see below).\r\n```\r\ny.enabled([])\r\n@y()\r\ndef add2(x):\r\n return x + 2\r\n```\r\nwould fail with`TypeError: 'NoneType' object is not callable`, but\r\n```\r\ny.enabled([])\r\n@y(decorator=True)\r\ndef add2(x):\r\n return x + 2\r\n```\r\nwill run correctly.\r\n\r\n\r\n## context_manager / cm\r\nNormally, an ycecream instance can be used as to show values, as a decorator and as a\r\ncontext manager.\r\n\r\nHowever, when used from a REPL the usage as a context manager can't be detected properly and in that case,\r\nspecify `context_manager=True`. E.g. \r\n```\r\n>>>with y(context_manager=True)\r\n>>> pass\r\ny| enter\r\ny| exit in 0.008644 seconds\r\n```\r\n\r\nThe `context_manager` attribute is also required when using `y():` as a context manager\r\nwith *fast disabling* (see below).\r\n```\r\ny.enabled([])\r\nwith y:\r\n pass\r\n```\r\nwould fail with `AttributeError: __enter__`, but\r\n```\r\ny.enabled([])\r\nwith y(context_manager=True):\r\n pass\r\n```\r\nwill run correctly.\r\n\r\n## provided / pr\r\nIf provided is False, all output for this call will be suppressed.\r\nIf provided is True, output will be generated as usual (obeying the enabled attribute).\r\n\r\n```\r\nx = 1\r\ny(\"should print\", provided=x > 0)\r\ny(\"should not print\", provided=x < 0)\r\n```\r\nThis will print\r\n```\r\nshould print\r\n```\r\n\r\n# Return a string instead of sending to output\r\n\r\n`y(*args, as_str=True)` is like `y(*args)` but the output is returned as a string instead\r\nof written to output.\r\n\r\n```\r\nfrom ycecream import y\r\nhello = \"world\"\r\ns = y(hello, as_str=True)\r\nprint(s, end=\"\")\r\n```\r\nprints\r\n```\r\ny| hello: 'world'\r\n```\r\n\r\nNote that if enabled=False, the call will return the null string (`\"\"`).\r\n\r\n# Disabling ycecream's output\r\n\r\n```\r\nfrom ycecream import y\r\nyd = y.fork(show_delta=True)\r\ny(1)\r\nyd(2)\r\ny.enabled = False\r\ny(3)\r\nyd(4)\r\ny.enabled = True\r\ny(5)\r\nyd(6)\r\nprint(y.enabled)\r\n```\r\nprints\r\n```\r\ny| 1\r\ny| delta=0.011826 ==> 2\r\ny| 5\r\ny| delta=0.044893 ==> 6\r\nTrue\r\n```\r\nOf course `y()` continues to return its arguments when disabled, of course.\r\n\r\nIt is also possible to suppress output with the provided attribute (see above).\r\n\r\n## Speeding up disabled ycecream\r\nWhen output is disabled, either via `y.configure(enbabled=False)` or `ycecream.enable = False`,\r\nycecream still has to check for usage as a decorator or context manager, which can be rather time\r\nconsuming.\r\n\r\nIn order to speed up a program with disabled ycecream calls, it is possible to specify\r\n`y.configure(enabled=[])`, in which case `y` will always just return\r\nthe given arguments. If ycecream is disabled this way, usage as a `@y()` decorator or as a `with y():`\r\ncontext manager will raise a runtime error, though. The `@y` decorator without parentheses will\r\nnot raise any exception, though.\r\n\r\nTo use `y` as a decorator and still have *fast disabling*:\r\n```\r\ny.configure(enabled=[])\r\n@y(decorator=True):\r\ndef add2(x):\r\n return x + 2\r\nx34 = add2(30)\r\n```\r\nAnd, similarly, to use `y` as a context manager combined with *fast disabling*:\r\n```\r\ny.configure(enabled=[])\r\nwith @y(context_manager=True):\r\n pass\r\n```\r\n\r\nThe table below shows it all.\r\n``` \r\n-------------------------------------------------------------------------------\r\n enabled=True enabled=False enabled=[]\r\n-------------------------------------------------------------------------------\r\nexecution speed normal normal fast \r\ny() normal no output no output\r\n@y normal no output no output\r\ny(decorator=True) normal no output no output\r\ny(context_manager=True) normal no output no output\r\n@y() normal no output TypeError\r\nwith y(): normal no output AttributeError/TypeError\r\ny(as_str=True) normal \"\" \"\"\r\n-------------------------------------------------------------------------------\r\n```\r\n\r\n# Using ycecream as a substitute for `assert`\r\n\r\nYcecream has a method `assert_` that works like `assert`, but can be enabled or disabled with the enabled flag.\r\n\r\n```\r\ntemperature = -1\r\ny.assert_(temperature > 0)\r\n```\r\nThis will raise an AttributeError.\r\n\r\nBut\r\n```\r\ny.enabled = False\r\ntemperature = -1\r\ny.assert_(temperature > 0)\r\n```\r\nwill not.\r\n\r\nNote that with the attribute propagation method, you can in effect have a layered assert system.\r\n\r\n# Interpreting the line number information\r\n\r\nWhen `show_line_number` is True or y() is used without any parameters, the output will contain the line number like:\r\n```\r\ny| #3 ==> a: 'abcd'\r\n```\r\nIf the line resides in another file than the main file, the filename (without the path) will be shown as well:\r\n```\r\ny| #30[foo.py] ==> foo: 'Foo'\r\n```\r\nAnd finally when used in a function or method, that function/method will be shown as well:\r\n```\r\ny| #456[foo.py] in square_root ==> x: 123\r\n```\r\nThe parent function can be suppressed by setting `show_line_number` or `sln` to `\"n\"` or `\"no parent\"`.\r\n\r\n# Configuring at import time\r\n\r\nIt can be useful to configure ycecream at import time. This can be done by providing a `ycecream.json` file which\r\ncan contain any attribute configuration overriding the standard settings.\r\nE.g. if there is an `ycecream.json` file with the following contents\r\n```\r\n{\r\n \"o\": \"stdout\",\r\n \"show_time\": true,\r\n \"line_length\": 120`\r\n 'compact' : true\r\n}\r\n```\r\nin the same folder as the application, this program:\r\n```\r\nfrom ycecream import y\r\nhello = \"world\"\r\ny(hello)\r\n```\r\nwill print to stdout (rather than stderr):\r\n```\r\ny| @ 14:53:41.392190 ==> hello: 'world'\r\n```\r\nAt import time the sys.path will be searched for, in that order, to find an `ycecream.json` file and use that. This mean that \r\nyou can place an `ycecream.json` file in the site-packages folder where `ycecream` is installed to always use\r\nthese modified settings.\r\n\r\nPlease observe that json values are slightly different from their Python equivalents:\r\n```\r\n-------------------------------\r\nPython json\r\n-------------------------------\r\nTrue true\r\nFalse false\r\nNone none\r\nstrings always double quoted\r\n-------------------------------\r\n```\r\nNote that not-specified attributes will remain the default settings.\r\n\r\nFor obvious reasons, it is not possible to specify `serialize` in an ycecream.json file.\r\n\r\n# Working with multiple instances of y\r\n\r\nNormally, only the `y()` object is used.\r\n\r\nIt can be useful to have multiple instances, e.g. when some of the debugging has to be done with context information\r\nand others requires an alternative prefix.\r\n\r\nTHere are several ways to obtain a new instance of ycecream:\r\n\r\n* by using `y.new()`\r\n \r\n With this a new ycecream object is created with the default attributes\r\n and possibly ycecream.json overrides.\r\n* by using `y.new(ignore_json=True)`\r\n\r\n With this a new ycecreamobject is created with the default attibutes. Any ycecream.json files asre ignored.\r\n* by using `y.fork()`\r\n \r\n With this a new ycecream object is created with the same attributes as the object it is created ('the parent') from. Note that any non set attributes are copied (propagated) from the parent.\r\n* by using `y.clone()`, which copies all attributes from y()\r\n\r\n With this a new ycecream object is created with the same attributes as the object it is created ('the parent') from. Note that the attributes are not propagated from the parent, in this case.\r\n\r\n* with `y()` used as a context manager\r\n \r\nIn either case, attributes can be added to override the default ones.\r\n\r\n### Example\r\n```\r\nfrom ycecream import y\r\ny_with_line_number = y.fork(show_line_number=True)\r\ny_with_new_prefix = y.new(prefix=\"==> \")\r\ny_with_new_prefix_and_time = y_with_new_prefix.clone(show_time=True)\r\nhello=\"world\"\r\ny_with_line_number(hello)\r\ny_with_new_prefix(hello)\r\ny_with_new_prefix_and_time(hello)\r\ny.equals_separator = \" == \" # this affects only the forked objects\r\ny_with_line_number(hello)\r\ny_with_new_prefix(hello)\r\ny_with_new_prefix_and_time(hello)\r\nwith y(prefix=\"ycm \") as ycm:\r\n ycm(hello)\r\n y(hello)\r\n```\r\nprints\r\n```\r\ny| #6 ==> hello: 'world'\r\n==> hello: 'world'\r\n==> @ 09:55:10.883732 ==> hello: 'world'\r\ny| #10 ==> hello == 'world'\r\n==> hello: 'world'\r\n==> @ 09:55:10.910717 ==> hello: 'world'\r\nycm enter\r\nycm hello == 'world'\r\ny| hello == 'world'\r\nycm exit in 0.017686 seconds\r\n```\r\n\r\n## ignore_json\r\nWith `y.new(ignore_json=True)` an instance of y without having applied any json configuration file will be returned. That can be useful when guaranteeing the same output in several setups.\r\n\r\n### Example\r\nSuppose we have an `ycecream.json` file in the current directory with the contents\r\n```\r\n{prefix=\"==>\"}\r\n```\r\nThen\r\n```\r\ny_post_json = y.new()\r\ny_ignore_json = y.new(ignore_json=True)\r\nhello = \"world\"\r\ny(hello)\r\ny_post_json(hello)\r\ny_ignore_json(hello)\r\n```\r\nprints\r\n```\r\n==>hello: 'world'\r\n==>hello: 'world'\r\ny| hello: 'world'\r\n```\r\n\r\n# Test script\r\n\r\nOn GitHub is a file `test_ycecream.py` that tests (and thus also demonstrates) most of the functionality\r\nof ycecream.\r\n\r\nIt is very useful to have a look at the tests to see the features (some may be not covered (yet) in this readme).\r\n\r\n# Using ycecream in a REPL\r\n\r\nYcecream may be used in a REPL, but with limited functionality:\r\n* all arguments are just presented as such, i.e. no left-hand side, e.g.\r\n ```\r\n >> hello = \"world\"\r\n >>> y(hello, hello * 2)\r\n y| 'hello', 'hellohello'\r\n ('hello', 'hellohello')\r\n ```\r\n* line numbers are never shown \r\n* use as a decorator is only supported when you used as `y(decorator=True)` or `y(d=1)`\r\n* use as a context manager is only supported when used as `y(context_manager=True)`or `y(cm=1)`\r\n\r\n# Alternative to `y`\r\n\r\nSometimes, it is not suitable to use the name y in a program, e.g. when\r\ndealing with coordinates x, y and z.\r\n\r\nIn that case, it is possible to use yc instead\r\n```\r\nfrom ycecream import yc\r\n```\r\nThe `yc` object is a *fork* of y with the prefix `\"yc| \"`. That means that attributes of `y` are propagated to `yc`, unless overridden.\r\n\r\nOf course, it is also possible to use\r\n```\r\nfrom ycecream import y as yy\r\n```\r\nor\r\n```\r\nyy = y.new()\r\n```\r\nor\r\n```\r\nyy = y.new(prefix=\"yy| \")\r\n```\r\n\r\n# Alternative installation\r\n\r\nWith `install ycecream from github.py`, you can install the ycecream.py directly from GitHub to the site packages (as if it was a pip install).\r\n\r\nWith `install ycecream.py`, you can install the ycecream.py in your current directory to the site packages (as if it was a pip install).\r\n\r\nBoth files can be found in the GitHub repository (https://github.com/salabim/ycecream).\r\n\r\n\r\n# Limitations\r\n\r\nIt is not possible to use ycecream:\r\n* from a frozen application (e.g. packaged with PyInstaller)\r\n* when the underlying source code has changed during execution\r\n\r\n# Implementation details\r\n\r\nAlthough not important for using the package, here are some implementation details:\r\n* ycecream.py contains the complete source of the asttokens and executing packages, in\r\n order to offer the required source lookups, without any dependencies\r\n* ycecream.py contains the complete source of pprint as of Python 3.8 in order to support the sort_dicts parameter, Under Python 2.7 this is ignored and the pprint module\r\nfrom the standard library is used.\r\n* in order to support using y() as a decorator and a context manager, ycecream caches the complete source of\r\nany source file that uses y()\r\n\r\n\r\n# Acknowledgement\r\n\r\nThe **ycecream** pacakage is inspired by the **IceCream** package, but is a \r\nnearly complete rewrite. See https://github.com/gruns/icecream\r\n\r\nMany thanks to the author Ansgar Grunseid / grunseid.com / grunseid@gmail.com .\r\n\r\n# Differences with IceCream\r\n\r\nThe ycecream module was originally a fork of IceCream, but has many differences:\r\n\r\n```\r\n----------------------------------------------------------------------------------------\r\ncharacteristic ycecream IceCream\r\n----------------------------------------------------------------------------------------\r\nplatform Python 2.7, >=3.6, PyPy Python 2.7, >=3.5, PyPy\r\ndefault name y (or yc) ic\r\ndependencies none many\r\nnumber of files 1 several\r\nusable without installation yes no\r\ncan be used as a decorator yes no\r\ncan be used as a context manager yes no\r\ncan show traceback yes no\r\nPEP8 (Pythonic) API yes no\r\nsorts dicts no by default, optional yes\r\nsupports compact, indent and\r\ndepth parameters of pprint yes no\r\nuse from a REPL limited functionality no\r\nexternal configuration via json file no\r\nobserves line_length correctly yes no\r\nbenchmarking functionality yes no\r\nsuppress f-strings at left hand optional no\r\nindentation 4 blanks (overridable) dependent on length of prefix\r\nforking and cloning yes no\r\ntest script pytest unittest\r\ncolourize no yes (can be disabled)\r\n----------------------------------------------------------------------------------------\r\n*) sort_dicts and compact are ignored under Python 2.7\r\n\r\n",
"bugtrack_url": null,
"license": "",
"summary": "ycecream",
"version": "1.3.17",
"project_urls": {
"Download": "https://github.com/salabim/ycecream",
"Homepage": "https://github.com/salabim/ycecream"
},
"split_keywords": [
"debugging",
"utility",
"tool",
"benchmarking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "098f076cab3636e474d5ae21b4e917f632ad5fd2f654d178699aab2ff986d0a3",
"md5": "802491d2c477591636f029c7667f5c27",
"sha256": "248f07e908dc2ddddaab12c03de54567cefe807341e710666c904a1a29fa1106"
},
"downloads": -1,
"filename": "ycecream-1.3.17.tar.gz",
"has_sig": false,
"md5_digest": "802491d2c477591636f029c7667f5c27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 100798,
"upload_time": "2023-12-04T09:36:18",
"upload_time_iso_8601": "2023-12-04T09:36:18.919448Z",
"url": "https://files.pythonhosted.org/packages/09/8f/076cab3636e474d5ae21b4e917f632ad5fd2f654d178699aab2ff986d0a3/ycecream-1.3.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-04 09:36:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "salabim",
"github_project": "ycecream",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ycecream"
}
JSON
