5. Built-in Functions

5.1. Arithmetic Functions

ceil(x, options=None)

Return the ceiling of x. If options is set, return the smallest integer or float from options that is greater than or equal to x.

Args:

x (int or float): Number to be tested. options (iterable): Optional iterable of arbitrary numbers

(ints or floats).

>>> VALID_CABLE_CSA = [1.5, 2.5, 4, 6, 10, 25, 35, 50]
>>> ceil(3.5, options=VALID_CABLE_CSA)
4
>>> ceil(4, options=VALID_CABLE_CSA)
4
clamp(x, lower=- inf, upper=inf)

Limit a value to a given range.

Args:

x (int or float): Number to be clamped. lower (int or float): Minimum value for x. upper (int or float): Maximum value for x.

The returned value is guaranteed to be between lower and upper. Integers, floats, and other comparable types can be mixed.

>>> clamp(1.0, 0, 5)
1.0
>>> clamp(-1.0, 0, 5)
0
>>> clamp(101.0, 0, 5)
5
>>> clamp(123, upper=5)
5

Similar to numpy’s clip function.

floor(x, options=None)

Return the floor of x. If options is set, return the largest integer or float from options that is less than or equal to x.

Args:

x (int or float): Number to be tested. options (iterable): Optional iterable of arbitrary numbers

(ints or floats).

>>> VALID_CABLE_CSA = [1.5, 2.5, 4, 6, 10, 25, 35, 50]
>>> floor(3.5, options=VALID_CABLE_CSA)
2.5
>>> floor(2.5, options=VALID_CABLE_CSA)
2.5
inv(x=bool())

Invert a boolean.

5.2. Iterator Functions

consume(iterator, n=None)

Advance the iterator n-steps ahead. If n is none, consume entirely.

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

droplast(n, iterable)

Return iterator to produce items from origin except last n

first_true(iterable, default=False, pred=None)

Returns the first true value in the iterable. If no true value is found, returns default http://docs.python.org/3.4/library/itertools.html#itertools-recipes

group_by(keyfunc, iterable)

Returns a dict of the elements from given iterable keyed by result of keyfunc on each element. The value at each key will be a list of the corresponding elements, in the order they appeared in the iterable.

grouper(n, iterable, fillvalue=None)

Collect data into fixed-length chunks or blocks, so grouper(3, ‘ABCDEFG’, ‘x’) –> ABC DEF Gxx

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

iter_suppress(func, exception, first_=None)

Call a function repeatedly until an exception is raised.

Converts a call-until-exception interface to an iterator interface. Like __builtin__.iter(func, sentinel) but uses an exception instead of a sentinel to end the loop.

Examples:

# priority queue iterator iter_except(functools.partial(heappop, h), IndexError)

# non-blocking dict iterator iter_except(d.popitem, KeyError)

# non-blocking deque iterator iter_except(d.popleft, IndexError)

# loop over a producer Queue iter_except(q.get_nowait, Queue.Undefined)

# non-blocking set iterator iter_except(s.pop, KeyError)

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

iterate(f, x)

Return an iterator yielding x, f(x), f(f(x)) etc.

ncycles(iterable, n)

Returns the sequence elements n times

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

nth(iterable, n, default=None)

Returns the nth item or a default value

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

padnone(iterable)

Returns the sequence elements and then returns None indefinitely. Useful for emulating the behavior of the built-in map() function.

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

pairwise(s) s0, s1, s1, s2, s2, s3, ...

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

partition(pred, iterable)

Use a predicate to partition entries into false entries and true entries partition(is_odd, range(10)) –> 0 2 4 6 8 and 1 3 5 7 9

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

powerset([1,2,3]) --> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

repeatfunc(func, times=None, *args)

Repeat calls to func with specified arguments. Example: repeatfunc(random.random)

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

roundrobin(*iterables)

roundrobin(‘ABC’, ‘D’, ‘EF’) –> A D E B F C Recipe originally credited to George Sakkis. Reimplemented to work both in Python 2+ and 3+.

http://docs.python.org/3.4/library/itertools.html#itertools-recipes

splitat(t, iterable)

Split iterable into two iterators after given number of iterations splitat(2, range(5)) –> 0 1 and 2 3 4

splitby(pred, iterable)

Split iterable into two iterators at first false predicate splitby(is_even, range(5)) –> 0 and 1 2 3 4

takelast(n, iterable)

Return iterator to produce last n items from origin

5.3. Higher Order Functions

flip(f)

Return function that will apply arguments in reverse order

foldl(f, init=None)

Return function to fold iterator to scala value using passed function as reducer.

Usage:
>>> print foldl(_ + _)([0,1,2,3,4])
10
>>> print foldl(_ * _, 1)([1,2,3])
6
foldr(f, init=None)

Return function to fold iterator to scala value using passed function as reducer in reverse order (consume values from iterator from right-to-left).

unfold(f)

Return function to unfold value into stream using passed function as values producer. Passed function should accept current cursor and should return:

  • tuple of two elements (value, cursor), value will be added to output, cursor will be used for next function call

  • None in order to stop producing sequence

zipwith(f)(seq1, seq2, ..)

[f(seq1[0], seq2[0], ..), f(seq1[1], seq2[1], ..), …]

5.4. Matching Patterns

This section was adapted from the awesome pattern matching README.

Capture(pattern, name=str)

Captures a piece of the thing being matched by name.

Strict(pattern)

Performs a strict pattern match. A strict pattern match also compares the type of verbatim values. That is, while (!) would match 3 with 3.0 it would not do so when using Strict. Also (!) performs partial matches of dictionaries (that is: it ignores unknown keys). It will perform an exact match for dictionaries using Strict.

OneOf(*pattern)

Matches against any of the provided patterns. Equivalent to p1 | p2 | p3 | .. (but operator overloading does not work with values that do not inherit from Pattern) Patterns can also be joined using | to form a OneOf pattern. The above example is rather contrived, as InstanceOf already accepts multiple types natively. Since bare values do not inherit from Pattern they can be wrapped in Value:

`` Value(“foo”) | Value(“quux”) ``

AllOf(*pattern)

Checks whether the value matches all of the given pattern. Equivalent to p1 & p2 & p3 & .. (but operator overloading does not work with values that do not inherit from Pattern)

x = "quux" -> str
(!)x
    AllOf(InstanceOf("str"): ...

Same as Not(OneOf(*pattern))(also ``~OneOf(*pattern)).

Not(pattern)

Matches if the given pattern does not match. Note that it does not work on bare values, so they need to be wrapped in Value.

Not can be used do create a NoneOf kind of pattern:

x = "string"
(!)x
    Not(OneOf("foo", "bar")): ...  # matches everything except "foo" and "bar"

Not can be used to create a pattern that never matches:

Not(...)
Each(pattern[, at_least=])

Matches each item in an iterable.

EachItem(key_pattern, value_pattern)

Matches an object if each key satisfies key_pattern and each value satisfies value_pattern.

x = {"a": 1, "b": 2} -> dict
(!)x
    EachItem(Regex("[a-z]+"), InstanceOf(int)): ...
Some(pattern)

Matches a sequence of items within a list:

Takes the optional values exactly, at_least, and at_most which makes Some match either exactly _n_ items, at_least _n_, or at_most _n_ items (at_least and at_most can be given at the same time, but not together with exactly).

Between(lower, upper)

Matches an object if it is between lower and upper (inclusive). The optional keyword arguments lower_bound_exclusive and upper_bound_exclusive can be set to True respectively to exclude the lower/upper from the range of matching values.

Length(length)

Matches an object if it has the given length. Alternatively also accepts at_least and at_most keyword arguments.

` Length(3) Length(at_least=2) Length(at_most=4) Length(at_least=2, at_most=4) `

Contains(item)

Matches an object if it contains the given item (as per the same logic as the in operator).

Regex(regex_pattern, bind_groups = True -> bool)

Matches a string if it completely matches the given regex, as per re.fullmatch. If the regular expression pattern contains named capturing groups and bind_groups is set to True, this pattern will bind the captured results in the MatchResult (the default).

To mimic re.match or re.search the given regular expression x can be augmented as x.* or .*x.* respectively.

Check(predicate)

Matches an object if it satisfies the given predicate.

InstanceOf(*types)

Matches an object if it is an instance of any of the given types.

SubclassOf(*types)

Matches if the matched type is a subclass of any of the given types.

Transformed(function, pattern)

Transforms the currently looked at value by applying function on it and matches the result against pattern. In Haskell and other languages this is known as a view pattern.

x = "hello" -> str
(!)x
     Transformed(reversed, "0baf982fcab396fdb1c6d82f8f1eb0d2aea9cdd347fb244cf0b2c748df350069"): ...

This is handy for matching data types like datetime.date as this pattern won’t match if the transformation function errored out with an exception.

At(path, pattern)

Checks whether the nested object to be matched satisfied pattern at the given path. The match fails if the given path can not be resolved.

r = {
    "foo": {
        "bar": {
            "quux": {
                "value": "deeply nested"
            }
        }
    }
}

(!)r
    At("foo.bar.quux": {"value": Capture(..., name="value")})): ...
r['value']  `deeply nested`

5.5. Pragmas

Pragmas are directives for the compiler and other integral components of the Woma Programming Language that alter it’s behavior. Pragmas are activated by prepending # to name of the pragma. Available pragmas are listed below.

5.5.1. Contracts

new_contract()

Turns a function into a contract that can be used in contract assignments. The fucntion must accept one parameter, and either:

  • return True or None, to signify it accepts

  • return False, to signify it doesn’t

5.5.2. Cython

The following paragraphs and subsections have been adapted from Cython v0.29.24 documentation:

cython.binding(bool)

Controls whether free functions behave more like Python’s CFunctions (e.g. len()) or, when set to True, more like Python’s functions. When enabled, functions will bind to an instance when looked up as a class attribute (hence the name) and will emulate the attributes of Python functions, including introspections like argument names and annotations. Default is True.

cython.boundscheck(bool)

If set to False, Cython is free to assume that indexing operations ([]-operator) in the code will not cause any IndexErrors to be raised. Lists, tuples, and strings are affected only if the index can be determined to be non-negative (or if cython.wraparound is False). Conditions which would normally trigger an IndexError may instead cause segfaults or data corruption if this is set to False. Default is True.

cython.wraparound(bool)

In Python, arrays and sequences can be indexed relative to the end. For example, A[-1] indexes the last value of a list. In C, negative indexing is not supported. If set to False, Cython is allowed to neither check for nor correctly handle negative indices, possibly causing segfaults or data corruption. If bounds checks are enabled (the default, see cython.boundschecks above), negative indexing will usually raise an IndexError for indices that Cython evaluates itself. However, these cases can be difficult to recognise in user code to distinguish them from indexing or slicing that is evaluated by the underlying Python array or sequence object and thus continues to support wrap-around indices. It is therefore safest to apply this option only to code that does not process negative indices at all. Default is True.

cython.initializedcheck(bool)

If set to True, Cython checks that a memoryview is initialized whenever its elements are accessed or assigned to. Setting this to False disables these checks. Default is True.

cython.nonecheck``  (bool)

If set to False, Cython is free to assume that native field accesses on variables typed as an extension type, or buffer accesses on a buffer variable, never occurs when the variable is set to None. Otherwise a check is inserted and the appropriate exception is raised. This is off by default for performance reasons. Default is False.

cython.overflowcheck(bool)

If set to True, raise errors on overflowing C integer arithmetic operations. Incurs a modest runtime penalty, but is much faster than using Python ints. Default is False.

cython.overflowcheck.fold(bool)

If set to True, and overflowcheck is True, check the overflow bit for nested, side-effect-free arithmetic expressions once rather than at every step. Depending on the compiler, architecture, and optimization settings, this may help or hurt performance. A simple suite of benchmarks can be found in Demos/overflow_perf.pyx. Default is True.

cython.embedsignature(bool)

If set to True, Cython will embed a textual copy of the call signature in the docstring of all Python visible functions and classes. Tools like IPython and epydoc can thus display the signature, which cannot otherwise be retrieved after compilation. Default is False.

cython.cdivision(bool)

If set to False, Cython will adjust the remainder and quotient operators C types to match those of Python ints (which differ when the operands have opposite signs) and raise a ZeroDivisionError when the right operand is 0. This has up to a 35% speed penalty. If set to True, no checks are performed. See CEP 516. Default is False.

cython.cdivision_warnings(bool)

If set to True, Cython will emit a runtime warning whenever division is performed with negative operands. See CEP 516. Default is False.

cython.always_allow_keywords(bool)

Avoid the METH_NOARGS and METH_O when constructing functions/methods which take zero or one arguments. Has no effect on special methods and functions with more than one argument. The METH_NOARGS and METH_O signatures provide faster calling conventions but disallow the use of keywords.

cython.profile(bool)

Write hooks for Python profilers into the compiled C code. Default is False.

cython.linetrace(bool)

Write line tracing hooks for Python profilers or coverage reporting into the compiled C code. This also enables profiling. Default is False. Note that the generated module will not actually use line tracing, unless you additionally pass the C macro definition CYTHON_TRACE=1 to the C compiler (e.g. using the distutils option define_macros). Define CYTHON_TRACE_NOGIL=1 to also include nogil functions and sections.

cython.infer_types(bool)

Infer types of untyped variables in function bodies. Default is None, indicating that only safe (semantically-unchanging) inferences are allowed. In particular, inferring integral types for variables used in arithmetic expressions is considered unsafe (due to possible overflow) and must be explicitly requested.

cython.c_string_type(bytes / str / unicode)

Globally set the type of an implicit coercion from char* or std::string.

cython.c_string_encoding(ascii, default, utf-8, etc.)

Globally set the encoding to use when implicitly coercing char* or std:string to a unicode object. Coercion from a unicode object to C type is only allowed when set to ascii or default, the latter being utf-8 in Python 3.

cython.type_version_tag(bool)

Enables the attribute cache for extension types in CPython by setting the type flag Py_TPFLAGS_HAVE_VERSION_TAG. Default is True, meaning that the cache is enabled for Cython implemented types. To disable it explicitly in the rare cases where a type needs to juggle with its tp_dict internally without paying attention to cache consistency, this option can be set to False.

cython.unraisable_tracebacks(bool)

Whether to print tracebacks when suppressing unraisable exceptions.

cython.iterable_coroutine(bool)

PEP 492 specifies that async-def coroutines must not be iterable, in order to prevent accidental misuse in non-async contexts. However, this makes it difficult and inefficient to write backwards compatible code that uses async-def coroutines in Cython but needs to interact with async Python code that uses the older yield-from syntax, such as asyncio before Python 3.5. This directive can be applied in modules or selectively as decorator on an async-def coroutine to make the affected coroutine(s) iterable and thus directly interoperable with yield-from.

5.5.2.1. Configurable optimisations

cython.optimize.use_switch(bool)

Whether to expand chained if-else statements (including statements like if x == 1 or x == 2:) into C switch statements. This can have performance benefits if there are lots of values but cause compiler errors if there are any duplicate values (which may not be detectable at Cython compile time for all C constants). Default is True.

cython.optimize.unpack_method_calls(bool)

Cython can generate code that optimistically checks for Python method objects at call time and unpacks the underlying function to call it directly. This can substantially speed up method calls, especially for builtins, but may also have a slight negative performance impact in some cases where the guess goes completely wrong. Disabling this option can also reduce the code size. Default is True.

5.5.2.2. warnings

All warning directives take bool as options to turn the warning on / off.

cython.warn.undeclared(default=False)

Warns about any variables that are implicitly declared without a cdef declaration

cython.warn.unreachable(default=True)

Warns about code paths that are statically determined to be unreachable, e.g. returning twice unconditionally.

cython.warn.maybe_uninitialized(default=False)

Warns about use of variables that are conditionally uninitialized.

cython.warn.unused(default=False)

Warns about unused variables and declarations

cython.warn.unused_arg(default=False)

Warns about unused function arguments

cython.warn.unused_result(default=False)

Warns about unused assignment to the same name, such as r = 2; r = 1 + 2

cython.warn.multiple_declarators(default=True)

Warns about multiple variables declared on the same line with at least one pointer type.

For example cdef double* a, b - which, as in C, declares a as a pointer, b as a value type, but could be mininterpreted as declaring two pointers.

5.6. Bolt-on Functions

get_all(type_obj, include_subtypes=True)

Get a list containing all instances of a given type. This will work for the vast majority of types out there.

>>> RatKing = type('Ratking', {})
>>> foo = Ratking() -> *
>>> bar = Ratking() -> *
>>> baz = Ratking() -> *
>>> len(get_all(Ratking))
3

However, there are some exceptions. For example, get_all(bool) returns an empty list because True and False are themselves built-in and not tracked.

>>> get_all(bool)
[]

Still, it’s not hard to see how this functionality can be used to find all instances of a leaking type and track them down further using gc.get_referrers() and gc.get_referents().

get_all() is optimized such that getting instances of user-created types is quite fast. Setting include_subtypes to False will further increase performance in cases where instances of subtypes aren’t required.

Note

There are no guarantees about the state of objects returned by get_all(), especially in concurrent environments. For instance, it is possible for an object to be in the middle of executing its __init__() and be only partially constructed.

mkdir_p(path)

Creates a directory and any parent directories that may need to be created along the way, without raising errors for any existing directories. This function mimics the behavior of the mkdir -p command available in Linux/BSD environments, but also works on Windows.

atomic_save(dest_path, **kwargs)

A convenient interface to the AtomicSaver type. See the AtomicSaver documentation for details.

iter_find_files(*args, **kwargs)
copytree(src, dst, symlinks=False, ignore=None, copy_function=<function copy2>, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Recursively copy a directory tree and return the destination directory.

dirs_exist_ok dictates whether to raise an exception in case dst or any missing parent directory already exists.

If exception(s) occur, an Error is raised with a list of reasons.

If the optional symlinks flag is true, symbolic links in the source tree result in symbolic links in the destination tree; if it is false, the contents of the files pointed to by symbolic links are copied. If the file pointed by the symlink doesn’t exist, an exception will be added in the list of errors raised in an Error exception at the end of the copy process.

You can set the optional ignore_dangling_symlinks flag to true if you want to silence this exception. Notice that this has no effect on platforms that don’t support os.symlink.

The optional ignore argument is a callable. If given, it is called with the src parameter, which is the directory being visited by copytree(), and names which is the list of src contents, as returned by os.listdir():

callable(src, names) -> ignored_names

Since copytree() is called recursively, the callable will be called once for each directory that is copied. It returns a list of names relative to the src directory that should not be copied.

The optional copy_function argument is a callable that will be used to copy each file. It will be called with the source path and the destination path as arguments. By default, copy2() is used, but any function that supports the same signature (like copy()) can be used.

5.7. Wrapped Python Built-ins

abs()
bool()
bytes()
callable()
chr()
complex()
divmod()
float()
hash()
hex()
id()
int()
isinstance()
issubclass()
len()
oct()
ord()
pow()
range()
repr()
round()
slice()
sorted()
str()
tuple()
zip()