Pythas package full reference¶

Full reference for the Pythas package. Targeting developers.

pythas module¶

Pythonically import Haskell modules into your Python context.

Pythas will automatically find a Haskell module and parse it. It will then create a module containing calls to the Haskell FFI wrapping everything compatible in the imported module. These calls are subsequently compiled into a shared library and parsed by the Python part of Pythas. Ultimately, Pythas imports this shared library as a module-like object into Python and wraps the function calls accordingly. In effect, for the user the calls to the Haskell runtime are almost indistinguishable to common Python calls.

Submodules¶

haskell : Containing all source written in Haskell and a wrapper around the GHC instance.

parser : A basic parser for exported Haskell type declarations.

pythas.compiler module¶

API for Haskell compilation and binding.

class pythas.compiler.Compiler(flags=('-O2'))¶

Interface for the compiler used to create shared libraries.

Parameters: flags (Tuple[str]) – Compile time flags to append. Default value is using the “-O2” flag.

GHC_VERSION¶

Version number string of the used GHC instance.

Type: str

flags¶

Flags for compiler.

Type: tuple(str)

stack_usage¶

Enable the usage of stack for compilation. Will default to False if stack is not available.

Type: bool

_compile(name)¶

Compiles an FFI file, links its library and parses for infos.

Parameters: name (str) – Pathlike object to a Haskell file containing FFI exports.
Returns: (lib, parse_infos)
Return type: The linked library and its parsed infos

add_flag(flag)¶

Adds a flag to flags.

Parameters: flag (str) – A valid compile time flag.

compile(filename)¶

Creates an FFI file, compiles and links it against the Python runtime.

Parameters: filename (str) – Pathlike object to a Haskell source file.
Returns: ffi_libs – List of tuples of linked libraries and their respective parsed infos.
Return type: [(ctypes.CDLL, pythas.parser.data.ParseInfo)]

copy()¶

Creates a new instance of Compiler from an existing one. Flags and stack_usage will be consistent.

Returns: new – The new Compiler instance.
Return type: Compiler

remove_flag(flag)¶

Removes a flag from flags.

Parameters: flag (str) – A flag contained within flags.

class pythas.compiler.SourceModule(code, compiler=None, use_stack=True, flags=('-O2'))¶

Module created from inline Haskell source code. Will instantiate its own instance of Compiler unless an alternative is provided. Other settings will not be permanently made in the compiler instance.

Parameters

code (str) – The Haskell source code to construct the module from.
compiler (Compiler) – Compiler instance to use settings from.
use_stack (bool) – Use stack if available. Default value is True.
flags (Tuple[str]) – Compile time flags to append. Default value is using the “-O2” flag.

pythas.core module¶

Core module containing the main metaprogramming.

class pythas.core.PythasLoader(compiler, filename)¶

Creates the FFI, compiles and links Haskell modules.

Parameters

compiler (Compiler) – The compiler used to create the linked library.
filename (str) – Pathlike object locating the Haskell source file.

class pythas.core.PythasMetaFinder(compiler)¶

MetaPathFinder for Haskell source files.

Parameters: compiler (Compiler) – The compiler used to create the linked library.

find_spec : Entry point for path finding

pythas.core.install(compiler)¶

Installer for the PythasMetaFinder.

Parameters: compiler (Compiler) – The compiler used to create the linked library.

pythas.haskell module¶

The pythas.haskell module contains a wrapper around GHC and all the Haskell source Pythas is based on. After the installation of Pythas, the Haskell source files need to be compiled first. Subsequent imports of Pythas will not need any compilation and thus result in quicker import times.

Haskell source documentation¶

These parts of Python are split into three Haskell packages:

C-structs

This package may be useful in many contexts and is therefore available on Hackage. It provides types representing structs as known from the C programming language in Haskell.

Pythas-Types

The types in Pythas-Types are based on the struct types from C-structs. They provide a foundation for the interfacing over the FFIs of both Haskell and Python.

Pythas-FFI

Parsing, wrapping and code generation are contained in here. First an AST of the type declarations is parsed. This AST is then extended to utilize Pythas-Types compatible input and output data. The extended AST is compiled into a Haskell source module and its path returned.

pythas.haskell.ghc module¶

Wrapping functionality for GHC and STACK.

exception pythas.haskell.ghc.CompileError¶

class pythas.haskell.ghc.GHC¶

Pythas interface class for GHC.

static check_version(stack=False)¶

Checks if the GHC version required is installed.

Parameters: stack (bool) – If True check version of stack ghc.

:raises ImportError : Version-Number of GHC is too low:

static compile(filepath, libpath, use_stack=False, add_flags=(), _redirect=False)¶

Compiles a Haskell source file to a shared library.

Parameters

filepath (str) – Pathlike object referencing the Haskell source file.
libpath (str) – Pathlike object referencing the shared library file.
use_stack (bool) – If True uses stack ghc as compile command if available. Defaults to availability.
add_flags (Tuple[str]) – Additional flags handed to GHC. Default is empty.
_redirect (bool) – If True internal binaries are redirect into Pythas’ bin directory for clean pip uninstall. Default is False.

Returns

libpath – Pathlike object referencing the shared library path.

Return type

str

static compile_cmd(use_stack, options)¶

Generates the compile command to GHC.

Parameters

use_stack (bool) – If True uses stack ghc as compile command.
options (tuple(str)) – The flags handed to GHC.

Returns

command – The entire command to initiate compilation.

Return type

tuple(str)

static flags(filename, libname, use_stack, _redirect=False)¶

Creates the flags needed for successful compilation of Haskell FFI files using Pythas.

Parameters

filepath (str) – Pathlike object referencing the Haskell source file.
libpath (str) – Pathlike object referencing the shared library file.
use_stack (bool) – If True uses stack ghc as compile command.
_redirect (bool = False) – Internal binaries are redirect into Pythas’ bin directory for clean pip uninstall.

Returns

flags – Flags for compilation of filepath to shared library in libpath.

Return type

tuple(str)

static get_version(stack_ghc)¶

Retrieves the GHC version number. Defaults to getting it from the command line, reverts to the ghcversion.h header.

Parameters: stack_ghc (bool) – True if stack’s GHC is used.
Returns: version – Version number string.
Return type: str

See also

get_ghc_version_from_cmdln, get_ghc_version_from_header

:raises ImportError : Version-Number of GHC could not be found:

static get_version_from_cmdln(stack_ghc)¶

Retrieves the GHC version number from the command line.

Parameters: stack_ghc (bool) – True if stack’s GHC is used.
Returns: version – Version number string.
Return type: str

static get_version_from_header()¶

Retrieves the GHC version number from the ghcversion.h header.

Returns: version – Version number string.
Return type: str

:raises ImportError : Version-Number of GHC could not be found:

pythas.haskell.ghc.has_stack()¶

Looks for stack on the $PATH.

Returns: has_stack – True if stack is in $PATH.
Return type: bool

pythas.parser.data module¶

Data container classes for parsing.

class pythas.parser.data.FuncInfo(name, argtypes, restype, constructors, reconstructor, htype)¶

Container class for informations about a Haskell function.

name¶

The name of the function.

Type: str

argtypes¶

List with types of the function arguments.

Type: list(ctype)

restype¶

Return type of the function.

Type: ctype

constructors¶

List of functions converting Python types to their respective argtypes.

Type: list(callable)

reconstructor¶

Callable converting the restype back to a native Python type and releasing any memory allocated in the transferring process.

Type: callable

htype¶

Type as given by the Haskell FFI export.

Type: str

class pythas.parser.data.ParseInfo(name, dir, exported_mod, exported_ffi, func_infos)¶

Container class for informations about a Haskell source module.

name¶

Module name

Type: str

dir¶

Pathlike object to the source file.

Type: str

exported_mod¶

Exported functions according to the module header.

Type: set(str)

exported_ffi¶

Functions with an FFI export.

Type: set(str)

func_infos¶

Dictionary mapping function names to their respective FuncInfo instance.

Type: dict(str, FuncInfo)

pythas.parser.data._FuncInfo¶: alias of pythas.parser.data.FuncInfo

pythas.parser.data._ParseInfo¶: alias of pythas.parser.data.ParseInfo

pythas.parser.parse_file module¶

Parse Haskell modules/files.

pythas.parser.parse_file._parse_haskell(hs_lines, parse_info)¶

Parses lines of a Haskell source file.

Parameters

hs_lines (list(str)) – Lines of a Haskell source file.
parse_info (ParseInfo) – Container into which informations are to be stored.

Returns

parse_info – Informations parsed from hs_lines.

Return type

ParseInfo

pythas.parser.parse_file.find_module_statement(hs_cont, name)¶

Locates the module statement in a Haskell source file.

Parameters

hs_cont (str) – Content of a Haskell source file.
name (str) – Name of the Haskell module as given by file name.

Returns

posiiton – Index of the module statement in the hs_cont.

Return type

int

:raises SyntaxError : Haskell file module statement malformed:

pythas.parser.parse_file.parse_haskell(hs_file)¶

Parses a Haskell file for exported functions and ffi exports.

Parameters

hs_file (str) – Pathlike object referring to the Haskell source file.
Reuturns –
-------- –
parse_info (ParseInfo) – Informations parsed from hs_file.

pythas.parser.parse_file.parse_head(hs_lines, name)¶

Finds all the names that are exported according to the module statement.

Parameters

hs_lines (list(str)) – Lines of a Haskell source file
name (str) – Name of the Haskell module as given by file name.

Returns

exports – List of exported names or None if no exports statement is given.

Return type

list(str)

pythas.parser.parse_file.parse_line(line_nr, hs_line, parse_info)¶

Parses a single line of Haskell source code.

Parameters

linr_nr (int) – Line number of the current line.
hs_line (str) – Line of Haskell code.
parse_info (ParseInfo) – Container into which informations are to be stored.

pythas.parser.parse_type module¶

Parse Haskell type declarations.

pythas.parser.parse_type.argtype(hs_type)¶

Parser for the argument side types of a Haskell function.

Parameters: hs_type (str) – Argument side Haskell type.
Returns: arg – Tuple with the argument type and a callable that converts a conventional Python instance to an instance of the required type.
Return type: (type, callable)

pythas.parser.parse_type.hs2py(hs_type)¶

Maps Haskell to Python types.

Parameters: hs_type (str) – The Haskell type.
Returns: pytype – The Python type.
Return type: type

pythas.parser.parse_type.parse_type(line_nr, name, hs_type)¶

Parses the type of an FFI exported Haskell function or constant.

Parameters

line_nr (int) – Line number of the parsed line.
name (str) – Name of the function or constant.
hs_type (str) – Type declaration of the Haskell entity.

Returns

func_info – Parsed information about the function.

Return type

FuncInfo

:raises TypeError : Functions as arguments are not supported:

pythas.parser.parse_type.restype(hs_type)¶

Parser for the result side type of a Haskell function.

Parameters: hs_type (str) – Result side Haskell type.
Returns: res – Tuple with the result type and a callable that converts the type to a conventional Python type.
Return type: (type, callable)

pythas.parser.parse_type.simple_hs_2_py(hs_type)¶

Converts simple Haskell types to their Python equivalent.

Parameters: hs_type (str) – The Haskell type.
Returns: pytype – The Python type.
Return type: type

Warning

TypeWarning : Custom types are an experimental feature in Pythas.

pythas.parser.utils module¶

Utility functions for parsing Haskell.

exception pythas.parser.utils.TypeWarning¶: Warning reminding the user that the types used by them are currently only under experimental support.

See also

Warning

pythas.parser.utils.apply(fs, t)¶

Weirdly similar to Haskell’s ap for subscriptable types.

Parameters

fs (iterable) – List of tuples which have a callable as second member.
t (iterable) – Arguments for the callable.

Returns

applied – Results of the application of the callables to the arguments in t with the same index.

Return type

tuple

pythas.parser.utils.lmap(f, xs)¶: Like map but returns a list instead of a generator.

pythas.parser.utils.match_parens(s, i)¶

Given a string and the index of the opening parenthesis returns the index of the closing one.

Parameters

s (str) – The string to match parentheses on.
i (int) – The initial index to start from.

Returns

closing – Index of the next matching closing paranthesis.

Return type

int

pythas.parser.utils.parse_generator(f_llist, f_carray, f_tuple, f_string, f_default)¶

Parser generator for parsing Haskell type statements.

Parameters

f_llist (callable) – Function to call in case of linked lists.
f_carray (callable) – Function to call in case of arrays.
f_tuple (callable) – Function to call in case of tuples.
f_string (callable) – Function to call in case of string.
f_default (callable) – Function to call in case of string.

Returns

parser – Function taking a string object with a Haskell type statement and parsing it using the appropriate function.

Return type

callable

pythas.parser.utils.strip_io(tp)¶

IO is somewhat disregarded in the FFI exports. IO CDouble looks the same as CDouble from Python’s side. So we remove the monadic part from our type to process the rest.

Parameters: tp (str) – Haskell type statement.
Returns: stripped – Tuple of ‘IO ‘ if there was an IO statement or the empty string if there was none and the rest of the type statement.
Return type: (str, str)

pythas.parser.utils.tuple_types(hs_type)¶

Extracts the types declarations inside a Haskell tuple type statement.

Parameters: hs_type (str) – Haskell type statement for a tuple.
Returns: types – Haskell type statements inside the tuple.
Return type: list(str)

pythas.types module¶

Custom types defined for Haskell FFI interfacing of complex, nested data.

class pythas.types.Array¶: Marker class for Pythas’ array types

class pythas.types.LinkedList¶: Marker class for Pythas’ linked lists

class pythas.types.Tuple¶: Marker class for Pythas’ tuples

pythas.types.from_c_array(cp_array)¶

Reconstructor from Pythas c_arrays.

Parameters: cp_array (cl.POINTER(Array)) – Pointer to an instance of a subclass of Array.
Returns: seq – A list with the contents of cp_array’s array.
Return type: list

pythas.types.from_linked_list(ll)¶

Reconstructor from Pythas linked lists.

Parameters: ll (LinkedList) – Pointer to the first element of a LinkedList instance.
Returns: seq – A list with the contents of ll.
Return type: list

pythas.types.from_tuple(cpt)¶

Reconstructor from Pythas c_tuples.

Parameters: cpt (cl.POINTER(Tuple)) – Pointer to an instance of a subclass of Tuple.
Returns: tup – A tuple with the contents of cpt.
Return type: tuple

pythas.types.get_constructor(ctype)¶

Finds the constructor for a standard or custom ctypes type. The custom types are checked against the marker classes:

Array
Tuple
LinkedList

Parameters: ctype (ctypes type) – (Sub-)Class of ctypes._SimpleCData or ctypes.Structure.
Returns: constructor – Function creating an instance of ctype.
Return type: callable

pythas.types.new_c_array(ctype)¶

Creates a Pythas array class of ctype.

Parameters: ctype (ctypes type) – (Sub-)Class of ctypes._SimpleCData or ctypes.Structure.
Returns: c_array – Subclass of Array and ctypes.Structure.
Return type: ctypes type

pythas.types.new_linked_list(ctype)¶

Creates a Pythas linked list class of ctype.

Parameters: ctype (ctypes type) – (Sub-)Class of ctypes._SimpleCData or ctypes.Structure.
Returns: c_linked_list – Subclass of LinkedList and ctypes.Structure.
Return type: ctypes type

pythas.types.new_tuple(subtypes)¶

Creates a constructor for a Pythas tuple from Python tuples of subtypes.

Parameters: subtypes (Sequence of ctypes types) – (Sub-)Class of ctypes._SimpleCData or ctypes.Structure.
Returns: c_tuple – Subclass of Tuple and ctypes.Structure.
Return type: ctypes type

pythas.types.to_c_array(cls, seq)¶

Constructor function for Pythas array.

Any instance of Array must always be associated with its cls.

Parameters

cls (Array subclass) – A array class created with new_c_array.
seq (Sequence) – The sequence which needs to be converted to a c_array.

Returns

array – An instance of cls constructed from seq.

Return type

Array

See also

new_c_array

pythas.types.to_linked_list(cls, seq)¶

Constructor function for Pythas linked lists.

Any instance of LinkedList must always be associated with its cls.

Parameters

cls (LinkedList subclass) – A linked list class created with new_linked_list.
seq (Sequence) – The sequence which needs to be converted to a linked list.

Returns

linked_list – An instance of cls constructed from seq.

Return type

LinkedList

See also

new_linked_list

pythas.types.to_tuple(cls, tup)¶

Constructor function for Pythas tuples.

Any instance of LinkedList must always be associated with its cls.

Parameters

cls (Tuple subclass) – A tuple class created with new_tuple.
tup (tuple) – The tuple which needs to be converted to a Pythas Tuple.

Returns

tuple – An instance of cls constructed from tup.

Return type

Tuple

See also

new_tuple

pythas.utils module¶

Utility module for the Pythas API.

class pythas.utils.PythasFunc(name, func_info, funcPtr, destructorPtr=None)¶

Wrapper class for functions imported from a compiled Haskell module.

Parameters

name (str) – The name of the function.
func_info (parser.data.FuncInfo) – Parsed information about the function.
funcPtr (ctypes._FuncPtr) – The pointer to the function.
destructorPtr (ctypes._FuncPtr) – Pointer to the function releasing any memory allocated by the function in funcPtr. None if no destruction is required.

pythas.utils.check_has_ghc()¶

Looks for a valid GHC or STACK installation is available and in the PATH variable.

:raises ImportError : No means of Haskell compilation is available.:

pythas.utils.custom_attr_getter(obj, name)¶

Pythas modules’ __getattribute__ instance. Retrieves foreign functions imported from Haskell modules by their name. Creates a PythasFunc instance and calls the finalizer function if given.

Parameters

obj (module) – The module of the overridden __getattribute__ method.
name (str) – The name to be retrieved from the module.

Returns

res

Return type

Either a constant or an instance of PythasFunc

:raises AttributeError : No corresponding foreign import could be found for name.:

pythas.utils.ffi_libs_exports(ffi_libs)¶

Collects the exported function names of a sequence of FFI library tuples. (See below)

Parameters: ffi_libs (Sequence of tuples of the DLL import and its parser.data.ParseInfo) – All imported modules and their parsed information.
Returns: exports – Set with all the exported names of the imported modules.
Return type: Set[str]

pythas.utils.find_source(name, path, extension='.hs')¶

Discovery function for Haskell modules.

Parameters

name (str) – The name of the module.
path (str or path-like object) – The path of the source directory.
extension (str) – The file extension to be used. Default value is ‘.hs’.

Returns

source – List containing the source file path for module name. Empty list if it couldn’t be discovered.

Return type

List[str]

pythas.utils.flatten(seq)¶

Creates a list of all basal elements of a nested sequence.

Parameters: seq (Sequence) – An arbitrarily deep nested sequence.
Returns: flatseq – List of all basal elements of seq.
Return type: List

pythas.utils.is_constant(func_infos)¶

Checks if an imported function is actually a pure constant. Constants that have to go be wrapped in the IO monad for head storage (like lists) are considered impure.

Parameters: func_infos (parser.data.FuncInfo) – Parsed information about the function.
Returns: is_constant – True if the function is actually a constant.
Return type: bool

pythas.utils.remove_created_files(filename)¶

Removes all files created by Pythas during the compilation process.

Parameters: filename (str or path-like object) – Path to the Haskell module source file.

pythas.utils.shared_library_suffix()¶

Defines the file suffix for shared library files depending on the host operating system.

Returns: suffix – The correct suffix containing a dot like: ‘.so’ .
Return type: str