API Reference#

This page gives an collection of all public classes and functions that modifies and configures files and Jacquard attributes

jacquard.py#

class jacquard.jacquard.Jacquard(jqd_dict, name=None, parent=None, file_=None)#

Represents a model configuration, usually stored in JSON format with the order of items preserved and comments (beginning with ‘//’) stripped out. Keys in the JSON file which conform to Python variable names (e.g. “my_attribute” but not “My Attribute”) become attributes of the Jacquard object (e.g. instance.my_attribute).

Value attributes (e.g. value in {"key": value}) are stored as JacquardValue objects to facilitate type conversion and checking. So to access the raw value, write “instance.my_attribute.value” or, to convert it to a specified type, write instance.my_attribute.as_bool().

This all facilitates “pretty” error message generation, to provide the end-user with as much information about the source of an error as these are common when specifying a model.

A Jacquard can be constructed from three static methods:

  • from_file() to construct from a JSON file on-disk

  • from_string() to construct from a JSON-formatted string in-memory

  • from_dict() to construct from a dictionary in-memory

Note

  • Jacquard implements __contains__ for testing if a name is ‘in’ the set of attributes.

as_dict(value_type=None)#

Converts this entry to a primitive dictionary, using specified types for the keys and values.

Parameters:

value_type (type, optional) – Defaults to None. The type to which the values will be cast, or None to ignore casting.

Returns:

A dictionary containing the entry’s keys and values

Return type:

dict

property file#

The source used for creation of the Jacquard instance.

static from_dict(dict_, file_name='<from_dict>', root_name='<root>')#

Converts a raw dictionary to a Jacquard object.

Parameters:

  • dict (dict) – The dictionary to create a Jacquard from

  • file_name

  • root_name

Returns:

Jacquard

classmethod from_file(fp)#

Reads a Jacquard from a JSON file. Comments beginning with ‘//’ are ignored.

Parameters:

fp (str) – The path to the JSON file

Returns:

The Jacquard object representing the JSON file.

Return type:

Jacquard

Raises:

JacquardParseError – if there’s a problem parsing the JSON file

classmethod from_string(s, file_name='<from_str>', root_name='<root>')#

Reads a Jacquard from a JSON file as a string. Comments beginning with ‘//’ are ignored.

Parameters:

  • s (str) – The string containing the Jacquard data, in JSON format.

  • file_name (str) – Optional ‘file’ name for display purposes.

  • root_name (str) – Optional root name for display purposes.

Returns:

The Jacquard object representing the JSON file.

Return type:

Jacquard

Raises:

JacquardParseError – if there’s a problem parsing the JSON file

property name#

Short name of each part of the Jacquard. For non-root Jacquards, this will be the name of the attribute used to access this Jacquard from the parent.

property namespace#

The dot-separated namespace of this part of the full Jacquard.

property parent#

Pointer to the parent of non-root Jacquard.

serialize()#

Recursively converts the Jacquard back to primitive dictionaries

to_file(fp, sort_keys=False)#

Writes the Jacquard to a JSON file.

Parameters:

  • fp (str) – File path to the output files

  • sort_keys (bool, optional) – Defaults to True.

api.py#

exception jacquard.api.JacquardParseError#
exception jacquard.api.JacquardSpecificationError#
exception jacquard.api.JacquardTypeError#
class jacquard.api.JacquardValue(value, name, owner=None)#

Wraps the value of a Jacquard attribute to facilitate type-checking and pretty error messages.

as_bool()#

Resolves the value to bool

Raises:

JacquardTypeError – If the value cannot be resolved to bool

as_float()#

Resolves the value to float

Raises:

JacquardTypeError – If the value cannot be resolved to float

as_int()#

Resolves the value to int

Raises:

JacquardTypeError – If the value cannot be resolved to int

as_list(sub_type=None)#

Resolves the value to a list.

Parameters:

sub_type (type) – Optional. Specifies the expected contiguous (uniform) type of the list to convert to.

Returns:

The value, as a list

Return type:

list

as_path(parent=None, check_exist=False)#

Resolves the value to Path type (available only when using Python 3)

Parameters:

  • parent – Optional parent folder if this is a relative path

  • check_exist – Flag to check file existence

Raises:

JacquardTypeError – If the value cannot be resolved to Path

as_set(sub_type=None)#

Converts the value to a set.

Parameters:

sub_type (type) – Optional. Specifies the expected contiguous (uniform) type of the set to convert to.

Returns:

The value, as a set

Return type:

set

as_str()#

Resolves the value to str

Raises:

JacquardTypeError – If the value cannot be resolved to str

as_type(type_)#

Attempts to cast the value to a specified type.

Parameters:

type (type) – The type (e.g. int, float, etc.) to try to cast

Returns:

The value cast as type

Raises:

JacquardTypeError – if the casting could not be performed.

property namespace#

Dot-separated name of this jacquard value

jacquard.api.is_identifier(name)#

Tests that the name is a valid Python variable name and does not collide with reserved keywords

Parameters:

name (str) – Name to test

Returns:

If the name is ‘Pythonic’

Return type:

bool

jacquard.api.open_file(file_handle, **kwargs)#

Context manager for opening files provided as several different types. Supports a file handler as a str, unicode, pathlib.Path, or an already-opened handler.

Parameters:

  • file_handle (Union[str, unicode, Path, File]) – The item to be opened or is already open.

  • **kwargs – Keyword args passed to open(). Usually mode=’w’.

Yields:

File – The opened file handler. Automatically closed once out of context.

On this page
Show Source