Serializer¶

class py_css_styleguide.serializer.ManifestSerializer(compiler_support=None, evaluation_limit=None)[source]¶

Serialize parsed CSS to data suitable to Manifest.

Raises:

SerializerError – When there is an invalid syntax in parsed manifest.

Keyword Arguments:

compiler_support (string) – Sass compiler name to assume when it has not been defined in meta references. Default to ManifestSerializer._DEFAULT_COMPILER_SUPPORT.
evaluation_limit (int) – A limit of string character length for evaluation to avoid possibly Python crash with very large string to evaluate with ast.literal_eval (see Python documentation for detail). Default to ManifestSerializer._DEFAULT_EVALUATION_LIMIT.

_metas¶

Buffer to store serialized metas from parsed source.

Type:: collections.OrderedDict

_DEFAULT_SPLITTER¶

Default value splitter used for some structure kinds.

Type:: string

_DEFAULT_CLEANER¶

Default cleaner name.

Type:: string

_DEFAULT_COMPILER_SUPPORT¶

Default Sass compiler name.

Type:: string

_DEFAULT_EVALUATION_LIMIT¶

Default limit of string character length for evaluation. It has been set to 1000 characters which should be a reasonnable large limit in our context.

Type:: int

get_ref_varname(name)[source]¶

Shortcut to format a reference name to a reference selector name.

Internally we pass a reference name (like bar) to methods which was parsed in manifest from a CSS selector name (like .styleguide-foo-bar) but for some messages we need to display CSS selector name again.

Parameters:: name (string) – A reference name.
Returns:: CSS selector name.
Return type:: string

limit_evaluation_string(name, value)[source]¶

Truncate given string value to the string evaluation length limit.

If ManifestSerializer.evaluation_limit is 0 or None, no limit will be applied.

Parameters:

name (string) – Reference name only used in possible warning message.
value (string) – String value to limit if needed

Returns:

Truncated string if needed depending ManifestSerializer.evaluation_limit value.

Return type:

string

value_splitter(name, prop, value, mode, cleaner=None)[source]¶

Split a string into a list items.

Behavior depend on argument mode, either a simple split on white spaces or an evaluation for a list syntax.

Parameters:

name (string) – Reference name used when raising possible error.
prop (string) – Property name used when raising possible error.
value (string) – Property value to split.
mode (string) –
Splitter mode. Default should come from ManifestSerializer._DEFAULT_SPLITTER.

Available splitter are:
- white-space: Simply split a string on white spaces;
- object-list: Assume the string is a list object to parse;
- json-list: Old name for object-list, deprecated;
cleaner (string)

Returns:

List of values parsed from given original JSON list.

Return type:

list

serialize_to_string(name, datas)[source]¶

Serialize given datas to a string.

Simply return the value from required variable``value``.

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

Value.

Return type:

string

serialize_to_number(name, datas)[source]¶

Serialize given datas to a number.

Simply return the value from required variable``value`` coerced to a number type, either a integer or an float. Value must be a valid number. String, empty value or None is not a valid number and will raise an error.

Serializer will first try to convert string to an integer and if it fails it will switch to float. Finally if no conversion succeed, an error is raised.

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

Coerced value.

Return type:

integer or float

serialize_to_flat(name, datas)[source]¶

Serialize given datas to a flat structure KEY:VALUE where KEY comes from keys variable and VALUE comes from values variable.

This means both keys and values are required variable to be correctly filled (each one is a string of item separated with an empty space). Both resulting list must be the same length.

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

Flat dictionnay of serialized reference datas.

Return type:

dict

serialize_to_list(name, datas)[source]¶

Serialize given datas to a list structure.

List structure is very simple and only require a variable --items which is a string of values separated with an empty space. Every other properties are ignored.

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

List of serialized reference datas.

Return type:

list

serialize_to_nested(name, datas)[source]¶

Serialize given datas to a nested structure where each key create an item and each other variable is stored as a subitem with corresponding value (according to key index position).

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

Nested dictionnary of serialized reference datas.

Return type:

dict

serialize_to_complex(name, datas)[source]¶

Serialize given datas to any object from assumed JSON string.

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

Object depending from content.

Return type:

object

serialize_to_json(name, datas)[source]¶

Shortcut around ManifestSerializer.serialize_to_complex() to maintain support for deprecated structure name json and emit a deprecation warning.

Parameters:

name (string) – Name only used inside possible exception message.
datas (dict) – Datas to serialize.

Returns:

Object depending from content.

Return type:

object

get_meta_compiler(datas)[source]¶: Get enabled compiler declarations.

get_meta_reference_names(datas)[source]¶

Get enabled reference declarations.

This required declaration is readed from styleguide-metas-references rule that require either a --names or --auto variable, each one define the mode to enable reference:

Manually

Using --names which define a list of names to enable, every other non enabled rule will be ignored.

Section name (and so Reference name also) must not contains special character nor - so they still be valid variable name for almost any languages. For word separator inside name, use _.

Automatic

Using --auto variable every reference rules will be enabled. The value of this variable is not important as long as it is not empty.

In this mode, another variable is watched for, it is excludes which is a list of reference names to ignore.

If both of these variables are defined, only the manual enable mode “–names” is used.

Parameters:: datas (dict) – Data where to search for meta references declaration. This is commonly the fully parsed manifest.
Returns:: A list of reference names.
Return type:: list

get_reference(datas, name)[source]¶

Get serialized reference datas

Because every reference is turned to a dict (that stands on keys variable that is a list of key names), every variables must have the same exact length of word than the key name list.

A reference name starts with ‘styleguide-reference-’ followed by name for reference.

A reference can contains variable --structure to define serialization structure.

Parameters:

datas (dict) – Data where to search for reference declaration. This is commonly the fully parsed manifest.
name (string) – Reference name to get and serialize.

Returns:

Serialized reference datas.

Return type:

collections.OrderedDict

get_available_references(datas)[source]¶

Get available manifest reference names.

Every rules starting with prefix from nomenclature.RULE_REFERENCE are available references.

Only name validation is performed on these references.

Parameters:

datas (dict) – Data where to search for reference declarations.

Returns:

List of every available reference names. This is the real: name unprefixed.

Return type:

list

get_enabled_references(datas, meta_references)[source]¶

Get enabled manifest references declarations.

Enabled references are defined through meta references declaration, every other references are ignored.

Parameters:

datas (dict) – Data where to search for reference declarations. This is commonly the fully parsed manifest.
meta_references (list) – List of enabled reference names.

Returns:

Serialized enabled references datas.

Return type:

collections.OrderedDict

serialize(datas)[source]¶

Serialize datas to manifest structure with metas and references.

Only references are returned, metas are assigned to attribute ManifestSerializer._metas.

Parameters:: datas (dict) – Data where to search for reference declarations. This is commonly the fully parsed manifest.
Returns:: Serialized enabled references datas.
Return type:: collections.OrderedDict