2. Code reference of FreePHIL

2.1. Common functions

freephil.change_default_phil_values(master_phil_str, new_default_phil_str, phil_parse=None, expert_level=4, attributes_level=4)[source]

Function for updating the default values in a PHIL scope

Parameters:

  • master_phil_str (str) –

  • new_default_phil_str (str) –

  • phil_parse (function) – function for parsing PHIL (optional, defaults to freephil.parse)

  • expert_level (int) – optional, defaults to 4

  • attributes_level (int) – optional, defaults to 4

Returns:

the master_phil_str with the updated default values

Return type:

str

Raises:

  • Sorry – if unrecognized PHIL parameters are encountered

  • RuntimeError – if new value cannot be interpreted (e.g str instead of float)

freephil.find_scope(current_phil, scope_name)[source]

Finds first occurence of scope within a scope

Parameters:

  • current_phil (freephil.scope) – Phil object to be searched

  • scope_name – Scope name to be searched for

Returns:

First scope occurence

Return type:

freephil.scope

freephil.parse(input_string=None, source_info=None, file_name=None, converter_registry=None, process_includes=False, include_stack=None)[source]

Creates Phil object from a string or a file

Parameters:

  • input_string – String to be parsed

  • source_info – Description of the source. Defaults to file_name

  • file_name – Parse from a file

  • converter_registry – Custom converters (see Extending Phil)

  • process_includes – Enables processing include statement

  • include_stack –

Returns:

Phil object

Return type:

freephil.scope

freephil.process_command_line(args, master_string, parse=None)[source]

Processes command line arguments

Parameters:

  • args (list of strings) – command line arguments

  • master_string (str) – Phil string; the string is parsed internally

  • parse – function to parse master_string. Defaults to freephil.parse

Returns:

Parsed arguments

Return type:

freephil.command_line.process

freephil.show_attributes(self, out, prefix, attributes_level, print_width)[source]

Prints attributes of the Phil object (scope or definition) to a file

Parameters:

  • self (freephil.scope) – Phil object to be printed

  • out (str) – Output file name

  • prefix (str) –

  • attributes_level (int) – Verbosity of the attributes

  • print_width (int) – Max. lenght of a row

2.2. Phil object

For overview see Phil object (scope)

The Phil object can be:

  1. freephil.scope if it has multiple sub-objects (parameters) or it is root object

  2. freephil.definition if it consist of a single value.

Both types provides similar set of functions and attributes.

class freephil.scope(name, objects=None, primary_id=None, primary_parent_scope=None, is_disabled=False, is_template=0, where_str='', merge_names=False, style=None, help=None, caption=None, short_caption=None, optional=None, call=None, multiple=None, sequential_format=None, disable_add=None, disable_delete=None, expert_level=None, alias=None)[source]

Phil object. It should not be created by an user directly, but usually by parsing Phil string (see: freephil.parse())

Variables:

objects (list of freephil.scope or freephil.definition) – Actual items of the scope, can be itterated over.

Note

Nesting depth of the scope is limited by Python recursion limit (default 1000).

Attributes possible from parsing Phil string/file. Attribute levels are:

  1. level: help and alias

  2. level: everything, whose value is not None

  3. level: everything else

Variables:

  • help (str) – Help entry for the parameter

  • caption (str) – Caption

  • short_caption – Short caption

  • optional (bool) – Is optional?

  • type – Type (see Available .type)

  • multiple (bool) – Possible mltiple times? (see .multiple = True)

  • input_size – Input size

  • style –

  • call (function) – A function, if the scope should be callable

  • sequential_format –

  • disable_add –

  • disable_delete –

  • expert_level (int) – Expert level

  • deprecated –

  • alias – Alias

Other class variables:

Variables:

  • is_definition (bool) – Always True

  • is_scope (bool) – Always False

Other instance variables:

Variables:

  • name –

  • primary_id –

  • primary_parent_scope (freephil.scope) – Parent scope

  • is_disabled –

  • is_template –

  • where_str –

  • merge_names –

active_objects()[source]

Iterator over active objects

adopt_scope(other)[source]

Makes other scope member of this parent scope

Parameters:

other (freephil.scope or object) – scope to be adopted

alias_path()[source]

Get path alias

Return type:

str

as_str(prefix='', expert_level=None, attributes_level=0, print_width=None)[source]

Returns pretty print as a string.

Parameters:

  • prefix – Prefix

  • expert_level (int) – Expert verbosity

  • attributes_level (int) – Attributes verbosity

  • print_width (int) – Max. line width

Return type:

str

change_primary_parent_scope(new_value)[source]

Changes primary parent scope

Parameters:

new_value (freephil.scope) – New parent scope

Returns:

Copy of itself with new primary parent

clone(python_object, converter_registry=None)[source]

Clones Python object to new one, filtered through this scope.

Parameters:
Returns:

Filtered Python object

Return type:

freephil.scope_extract

command_line_argument_interpreter(home_scope=None, argument_description=None)[source]

Creates an interpreter of command line arguments for the scope

Parameters:

  • home_scope (freephil.scope) – Parse only within sub-scope

  • argument_description (str) – Description of arguments source. Defaults “command line”

Returns:

Command line interpreter

Return type:

freephil.command_line.argument_interpreter

copy()[source]

Copy the object

Return type:

freephil.scope

customized_copy(name=None, objects=None)[source]

Customized object copy, changing name of the object and sets new objects.

Parameters:

  • name (str) – New object name

  • objects – New objects

Returns:

Customized object copy

Return type:

freephil.scope

extract(parent=None)[source]

Extracts the Phil object into Python object.

Parameters:

parent (freephil.scope) – Set parent Phil object

Returns:

Python object

Return type:

freephil.scope_extract

extract_format(source=None)[source]

Performs extract-format of itself (or source)

Parameters:

source (freephil.scope or None) – None, or a scope

Returns:

Filtered scope by itself

Return type:

freephil.scope

fetch(source=None, sources=None, track_unused_definitions=False, diff=False, skip_incompatible_objects=False)[source]

Combine multiple Phil objects using the base Phil (self). Returns full Phil object with changes from sources applied. If an arguments occurs multiple times in different sources, the first from the list is used. For more details see fetch: merging of Phil objects.

Parameters:

  • source (freephil.scope) – Input Phil object

  • sources (list of freephil.scope) – Multiple input Phil objects

  • track_unused_definitions (bool) – If True, the function returns a tuple, where second member contains entries not used in base Phil object (see: fetch option: track_unused_definitions)

  • diff (bool) – If True, equivalent to fetch_diff()

  • skip_incompatible_objects (bool) – Skip incompatible object types

Returns:

Phil object, or Phil object and object with unprocessed data

Return type:

freephil.scope or tuple(freephil.scope, list of freephil.object_locator)

fetch_diff(source=None, sources=None, track_unused_definitions=False, skip_incompatible_objects=False)[source]

Creates difference Phil object containing only items, which differ between the base Phil object and source(s).

Parameters:

  • source (freephil.scope) – Input Phil object

  • sources (list of freephil.scope) – Multiple input Phil objects

  • track_unused_definitions (bool) – If True, the function returns a tuple, where second member contains entries not used in base Phil object (see: fetch option: track_unused_definitions)

  • diff (bool) – If True, equivalent to fetch_diff()

  • skip_incompatible_objects (bool) – Skip incompatible object types

Returns:

Phil object, or Phil object and object with unprocessed data

Return type:

freephil.scope or tuple(freephil.scope, list of freephil.object_locator)

format(python_object)[source]

Converts Python object into Phil object. It has to be called as a member function of the base Phil object to recover Phil metadata.

Parameters:

python_object (freephil.scope_extract) – Python object to be converted

Returns:

Phil object

Return type:

freephil.scope

full_path()[source]

Retuns full path to the scope as a string

Return type:

str

has_attribute_with_name(name)[source]

Checks for argument presence

Parameters:

name – Argument being checked

Returns:

True, if attribute exists in the scope

Return type:

bool

is_empty()[source]
Returns:

True, if object is empty

Return type:

bool

process_includes(converter_registry, reference_directory, include_stack=None)[source]

Manually triggers processing of Includes

Parameters:

  • converter_registry –

  • reference_directory –

  • include_stack –

show(out=None, merged_names=[], prefix='', expert_level=None, attributes_level=0, print_width=None)[source]

Pretty prints the Phil object

Parameters:

  • out (None or file) – If None, prints to sys.stdout, else to the file. The file has to be opened for writing.

  • merged_names –

  • prefix – Prefix

  • expert_level (int) – Expert verbosity

  • attributes_level (int) – Attributes verbosity

  • print_width (int) – Max. line width

Returns:

class freephil.definition(name, words, primary_id=None, primary_parent_scope=None, is_disabled=False, is_template=0, where_str='', merge_names=False, tmp=None, help=None, caption=None, short_caption=None, optional=None, type=None, multiple=None, input_size=None, style=None, expert_level=None, deprecated=None, alias=None)[source]

One line definitions used in Phil objects. The class is usually generated as part of parent freephil.scope

Attributes possible from parsing Phil string/file. Attribute levels are:

  1. level: help and alias

  2. level: everything, whose value is not None

  3. level: everything else

Variables:

  • help (str) – Help entry for the parameter

  • caption (str) – Caption

  • short_caption – Short caption

  • optional (bool) – Is optional?

  • type – Type (see Available .type)

  • multiple (bool) – Possible mltiple times? (see .multiple = True)

  • input_size – Input size

  • style –

  • expert_level (int) – Expert level

  • deprecated –

  • alias – Alias

Other class variables:

Variables:

  • is_definition (bool) – Always True

  • is_scope (bool) – Always False

Other instance variables:

Variables:

  • name –

  • words – Actual value (equivalent of objects in freephil.scope)

  • primary_id –

  • primary_parent_scope (freephil.scope) – Parent scope

  • is_disabled –

  • is_template –

  • where_str –

  • merge_names –

  • tmp –

alias_path()[source]

Returns alias of the definition.

Return type:

str

as_str(prefix='', expert_level=None, attributes_level=0, print_width=None)[source]

Returns pretty print of the definition as string

Parameters:

  • prefix (str) – Prefix

  • expert_level (int) – Maximal expert level

  • attributes_level (int) – Attribute level

  • print_width (int) – Maximum linewidth

Returns:

Pretty print of the definition

Return type:

str

copy()[source]

Copy of itself

Return type:

freephil.definition

customized_copy(name=None, words=None)[source]

Customized copy of itself, with new name and words

Parameters:

  • name (str) – New name

  • words – new value(s)

Return type:

freephil.definition

extract(parent=None)[source]

Extracts the Phil object definition into Python object.

Parameters:

parent (freephil.scope) – Set parent Phil object

Returns:

Python object

Return type:

freephil.scope_extract

extract_format(source=None)[source]

Performs extract-format of itself (or source)

Parameters:

source (freephil.scope or None) – None, or a scope

Returns:

Filtered scope by itself

Return type:

freephil.scope

fetch(source, diff=False, skip_incompatible_objects=False)[source]

Merge the definition with definitions from other source

Parameters:

  • source (freephil.definition) – Other definition to merge with

  • diff (bool) – If True, returns only differences.

  • skip_incompatible_objects (bool) – Skip incompatible objects

Returns:

fetch_diff(source, skip_incompatible_objects=False)[source]

Merges the definition with defintions from others sources, returns only difference

Parameters:

  • source –

  • skip_incompatible_objects –

Returns:

Phil object definition

Return type:

freephil.definition

format(python_object)[source]

Converts Python object into Phil object definition. It has to be called as a member function of the base Phil object definition to recover Phil metadata.

Parameters:

python_object (freephil.scope_extract) – Python object to be converted

Returns:

Phil definitio

Return type:

freephil.definition

full_path()[source]

Returns full path to the definition

Return type:

str

has_attribute_with_name(name)[source]

Returns True, if the atribute exists

Parameters:

name (str) – Attribue name

Return type:

bool

show(out=None, merged_names=[], prefix='', expert_level=None, attributes_level=0, print_width=None)[source]

Pretty prints the definition

Parameters:

  • out (None or file object) – If provided, writes to the file. The file had to be opened

  • merged_names (list of str) –

  • prefix (str) – Prefix

  • expert_level (int) – Maximal expert level

  • attributes_level (int) – Attribute level

  • print_width (int) – Maximum linewidth

2.3. Python object (scope_extract)

class freephil.scope_extract(name, parent, call)[source]

Python object (see Python object (scope_extract)). It is easy to access pythonic reprezentation of Phil object, but luckying metainformation, like expert_level. Further nested scopes and data are stored as attributes of the object.

Variables:

  • __phil_name__ – Phil name

  • __phil_parent__ – parent object

  • __phil_call__ – function to be called, if the scope is callable

__inject__(name, value)[source]

Creates new member object with name and value

Parameters:

  • name (str) – Object name

  • value – Object

Raises:

AttributeError – When attribute already exists

__phil_join__(other)[source]

Joins other object. The other object can have only subset of attributes

Parameters:

other (freephil.scope_extract) – Object to be joined in

__phil_path__(object_name=None)[source]

Returns fully qualified path of the scope. If object_name is given, path to the object is given

Parameters:

object_name (str) – Object of the scope_extract

Returns:

Fully qualified path

Return type:

str

__phil_path_and_value__(object_name)[source]

Retruns fully qualified path of the object and its value

Parameters:

object_name (str) – Object of the scope_extract

Returns:

Fully qualified name and object value

Return type:

tuple

2.4. Command line processing

class freephil.command_line.argument_interpreter(master_phil=None, home_scope=None, argument_description=None, master_params=None)[source]

Class of command line argument interpreter, based on base Phil object. The class is typically returned by freephil.scope.command_line_argument_interpreter()

Parameters:

  • master_phil (freephil.scope) – base Phil object

  • home_scope (str) – Home scope

  • argument_description (str) – Description of source of the arguments. Defaults to “command line”

  • master_params – deprecated (raises warning about it)

process(arg=None, args=None, custom_processor=None)[source]

Process string as command line argument.

Parameters:

  • arg (str) – One argument

  • args (list of str) – Arguments to be processed

  • custom_processor – Use custom Phil processor.

Returns:

Phil object

Return type:

freephil.scope

process_and_fetch(args, custom_processor=None, extra_sources=())[source]

Performs process and fetch in single command.

Parameters:

  • args (list of strings) – command line arguments

  • custom_processor – If set to “collect_remaining”, also unprocessed arguments are returned

  • extra_sources (list of freephil.scope) – other sources to be fetched with the parsed arguments.

Returns:

Phil object

Return type:

freephil.scope

class freephil.command_line.process(args, master_string, parse=None, extra_sources=())[source]

Governing class for command line processing

Parameters:

  • args (list of str) – Input command line arguments

  • master_string (str) – String defining base Phil

  • parse (function) – Custom parser function, defaults to freephil.parse

  • extra_sources (list of freephil.scope) – Other Phil objects to be fetch with

Variables:

  • work (freephil.scope) – Phil object from processed arguments

  • remaining_args (list of str) – Arguments, which could not be parsed

  • master (freephil.scope) – Base Phil object

show(out=None)[source]

Pretty prints the self.work.

Parameters:

out (None or file object) – Target of the print. If None, prints to stdout