ecstasy.parser

The heart of the ecstasy package, containing the main Parser class.

class ecstasy.parser.Parser(args, kwargs)[source]

Bases: object

Handles parsing and beautification of a string.

This is the main class of the entire ecastasy package. It is initialized with a set of positional and keyword arguments that determine which styles (flag-combinations) are used for which phrases (tag-marked regions of text) found during parsing. Its beautify() method is then used to beautify a string according to the arguments passed to the constructor.

Note

From the outside, the package-level beautify() method should handle the construction and beautify()-call process all-in-one (for convenience).

always

The list of ‘always’ (keyword) arguments.

positional

The list of positional arguments.

tags

A compiled regex matching opening or closing tags.

argument

A compiled regex matching well-formed phrase arguments.

counter

A counter for positional arguments.

beautify(string)[source]

Wraps together all actions needed to beautify a string, i.e. parse the string and then stringify the phrases (replace tags with formatting codes).

Parameters:

string (str) – The string to beautify/parse.

Returns:

The parsed, stringified and ultimately beautified string.

Raises:
  • errors.ArgumentError if phrases were found, but not a single style
  • (flag combination) was supplied.
close_phrase(string, root, pos)[source]

Helper function of self.parse() handling closing tags.

Parameters:
  • string (str) – The string being parsed.
  • root (Phrase) – The current root phrase.
  • pos (int) – The index/position of the closing tag in the string.
Returns:

Always the (possibly) escaped string, then either the fully formed phrase if the closing tag was not escaped (with its ‘closing’ and ‘string’ attributes set) and otherwise None, and lastly the next tag if the closing tag was indeed escaped and otherwise None – i.e. either the tuple (string, phrase, None) or (string, None, tag).

escape_meta(string, pos)[source]

Checks if a meta character is escaped or else warns about it.

If the meta character has an escape character (‘’) preceding it, the meta character is escaped. If it does not, a warning is emitted that the user should escape it.

Parameters:
  • string (str) – The relevant string in which the character was found.
  • pos (int) – The index of the meta character within the string.
Returns:

The possibly escaped string and the next meta match.

get_flags(args)[source]

Checks and retrieves positional and ‘always’ (keyword) flags from the many ways in which they may be passed to the constructor (or the beautify() method on package-level).

Positional arguments can be passed either:

  • Individually, where each flag-combination is one positional argument.
  • Packaged inside a list, which is then expanded. There can be multiple of such lists passed as arguments because it facilitates interaction with the ecastasy module (one may want to organize and update styles in certain ways depending on one’s program), but each list will be expanded and all flag-combinations found inside each list will be interpreted as a single style argument, as if it had been passed in the way desribed above (individually).

‘Always’ arguments can be passed either:

  • Individually, with keyword-argument syntax, i.e. <word>=<style>
  • In a dictionary, which is expanded exactly like positional arguments passed in lists (i.e. each key/value pair in the dictionary is interpreted as if it had been passed individually, as key=value to the constructor/the external beautify() method).

Note

self.always is set equal to the keyword arguments passed to the constructor and then modified directly (when ‘always’-arguments are found), while the positional arguments are put into a list here and returned (i.e. no interaction with self.positional).

Parameters:

args (list) – The positional arguments passed to the constructor.

Returns:

The positional arguments.

Raises:
  • errors.FlagError – If an invalid (out-of-range) flag combination was passed.
  • errors.EcstasyError – If one of the arguments is of invalid type.
handle_arguments(string, root, opening, closing)[source]

Handles phrase-arguments.

Sets the override and increment flags if found. Also makes sure that the argument sequence is at the start of the phrase and else warns about the unescaped meta characters. If the arguments are indeed at the start but do not match the arguments regular expression, an error is raised.

Parameters:
  • string (str) – The string being parsed.
  • root (str) – The current root phrase.
  • opening (int) – The index of the opening paranthese.
  • closing (int) – The index of the closing paranthese.
Returns:

The (possibly escaped) string, the root phrase (if no escaping, then with arguments and flags) and the next meta match.

Raises:

errors.ParseError – If the arguments are invalid.

open_phrase(string, pos)[source]

Helper function of self.parse() handling opening tags.

Parameters:
  • string (str) – The string being parsed.
  • pos (int) – The index/position of the opening tag in the string.
Returns:

The (possibly) escaped string, a child phrase if the opening tag was not escaped and otherwise None, and a new tag match, either starting at one index passed the escaped tag or one index passed the closing tag of the child.

parse(string, root=None)[source]

Parses a string to handle escaped tags and retrieve phrases.

This method works recursively to parse nested tags. When escaped tags are found, those are removed from the string. Also argument sequences are removed from the string. The string returned can thus be quite different from the string passed.

Parameters:
  • string (str) – The string to parse.
  • root (Phrase) – If in a recursive call, the root/parent phrase.
Returns:

For one, the escaped string (without escape characters and phrase arguments). For the other, it depends on the stack-depth. If this is the lowest recursion depth/level (i.e. the stack call resulting from the first function call in self.beautify()), it will return a list of phrases. For higher stack levels ( i.e. resulting from recursive function calls from with self.parse(), for nested phrases), it returns exactly one Phrase instance.

Raises:

errors.ParseError – If no closing tag could be found for an opening tag.

raise_not_enough_arguments(string)[source]

Raises an errors.ArgumentError if not enough arguments were supplied.

Takes care of formatting for detailed error messages.

Parameters:string (str) – The string of the phrase for which there weren’t enough arguments.
Raises:errors.ArgumentError with a detailed error message.
stringify(string, phrases, parent=None)[source]

Stringifies phrases.

After parsing of the string via self.parse(), this method takes the escaped string and the list of phrases returned by self.parse() and replaces the original phrases (with tags) with the Phrase-objects in the list and adds the appropriate flag-combinations as determined by the string or the position of the phrase (the string if it’s in self.always, i.e. an ‘always’ argument). This method also works recursively to handle nested phrases (and resetting of parent-phrase styles).

Parameters:
  • string (str) – The escaped string returned by self.parse().
  • phrases (list) – The list of Phrase-objects returned by self.parse().
  • parent (Phrase) – For recursive calls, the current parent Phrase.
Returns:

The finished, beautifully beautified string.

Raises:

errors.ArgumentError – If more positional arguments are requested than were supplied.

class ecstasy.parser.Phrase(opening=None, closing=None, string='', style=0, args=None, nested=None, override=False, increment=False)[source]

Bases: object

Class describing a single parsed phrase.

When a string is parsed in ecastasy, specially-marked regions of text are converted taken note of and converted into Phrase objects, which are later then used to replace the parsed strings (including any tags or arguments) with the string itself as well as the formatting codes specified by the arguments passed to Parser.beautify(), which are then interpreted by the command line.

string

str

The text of the phrase (between opening and closing tags).

opening

int

The index of the opening tag.

closing

int

The index of the closing tag.

style

int

The formatting/style flag-combination of the phrase.

nested

list

A list of nested Phrase objects (children).

override

bool

The phrase’s override specification.

ecstasy.parser.beautify(string, *args, **kwargs)[source]

Convenient interface to the ecstasy package.

Parameters:
  • string (str) – The string to beautify with ecstasy.
  • args (list) – The positional arguments.
  • kwargs (dict) – The keyword (‘always’) arguments.

ecstasy.errors

Custom error classes and helper functions for descriptive error-messages.

exception ecstasy.errors.ArgumentError(what)[source]

Bases: ecstasy.errors.EcstasyError

Raised when the positional argument for a phrase is out-of-range (i.e. there were fewer positional arguments passed to beautify() than requested in the argument).

exception ecstasy.errors.EcstasyError(what)[source]

Bases: exceptions.Exception

Base class for exceptions in Ecstasy.

what

str

A descriptive string regarding the cause of the error.

exception ecstasy.errors.FlagError(what)[source]

Bases: ecstasy.errors.EcstasyError

Raised when flag combinations are invalid.

exception ecstasy.errors.InternalError(what)[source]

Bases: ecstasy.errors.EcstasyError

Raised when something went wrong internally, i.e. within methods that are non-accessible via the API but are used for internal features or processing. Basically get mad at the project creator.

exception ecstasy.errors.ParseError(what)[source]

Bases: ecstasy.errors.EcstasyError

Raised when the string passed to the beautify() method is ill-formed and includes some syntactic badness such as missing closing tags.

ecstasy.errors.number(digit)[source]

Gets a spoken-word representation for a number.

Parameters:digit (int) – An integer to convert into spoken-word.
Returns:A spoken-word representation for a digit, including an article (‘a’ or ‘an’) and a suffix, e.g. 1 -> ‘a 1st’, 11 -> “an 11th”. Adittionally delimits characters in pairs of three for values > 999.
ecstasy.errors.position(string, index)[source]

Returns a helpful position description for an index in a (multi-line) string using the format line:column.

Parameters:
  • string (str) – The string to which the index refers.
  • index (int) – The index of the character in question.
Returns:

column where line refers to the 1-indexed row/line in which the character is found within the string and column to the position of the character within (relative to) that line.

Return type:

A string with the format line

ecstasy.errors.warn(what, string, pos)[source]

Combines a warning with a call to errors.position().

Simple convenience function.

Parameters:
  • string (str) – The string being parsed.
  • pos (int) – The index of the character that caused trouble.

ecstasy.flags

Formatting and style flags for ecstasy.

class ecstasy.flags.Color[source]

Bases: ecstasy.flags.Flags

Text color flags (not fill-color).

__str__()

Turns the flag into its style-code.

Returns:The flag’s style/formatting code.
class ecstasy.flags.Fill[source]

Bases: ecstasy.flags.Flags

Fill color flags (not text-color).

__str__()

Turns the flag into its style-code.

Returns:The flag’s style/formatting code.
class ecstasy.flags.Flags[source]

Bases: enum.Enum

Base class for all flag enum-classes as well as the individual flag objects/enum members inside the classes (by virtue of the enum.Enum semantics).

The most important re-defined method is __new__ which initializes a flag with a command-line format/style escape-code specific to the flag, as well as with a numeric value (power of 2) that depends on its position inside the enum-class and also on the position of the enum-class itself inside the order of enum classes (as the Hack mechanism will continuously increment flag values over multiple Flags sub-enum-classes). This class also defines various necessary operator and conversion overloads that define the semantics/interaction of flags (such as that you can bitwise-OR and bitwise-AND them).

class ecstasy.flags.Hack[source]

Bases: object

A hack namespace to make enumeration work continuously across multiple flag enum-classes. ‘last’ will be set to the last enumerated enum-class and start to the value at which the flag values of the enum-class currently being evaluated in the Flags.__new__() method start (i.e. start is the flag value of the previous enum-class left- shifted by one bit).

last

alias of Fill

start = 16777216
class ecstasy.flags.Style[source]

Bases: ecstasy.flags.Flags

Special formatting flags pertaining to any style alterations that do not involve color (but other factors of appearence).

__str__()

Turns the flag into its style-code.

Returns:The flag’s style/formatting code.
ecstasy.flags.codify(combination)[source]

Gets escape-codes for flag combinations.

Parameters:combination (int) – Either a single integer-convertible flag or an OR’d flag-combination.
Returns:A semi-colon-delimited string of appropriate escape sequences.
Raises:errors.FlagError if the combination is out-of-range.