xcookie.directive module

Port and extension of xdoctest directives.

xcookie.directive.named(key, pattern)

helper for regex

class xcookie.directive.Effect(action, key, value)

Bases: tuple

Create new instance of Effect(action, key, value)

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}

_fields = ('action', 'key', 'value')

classmethod _make(iterable)

Make a new Effect object from a sequence or iterable

_replace(**kwds)

Return a new Effect object replacing specified fields with new values

action

Alias for field number 0

key

Alias for field number 1

value

Alias for field number 2

xcookie.directive.extract_directive_comment(source)

Different than the xdoctest version. Finds the last comment part of a line

source = ‘# acommend # b comment’ list(extract_directive_comment(source))

# TODO: lark grammar?

class xcookie.directive.Directive(name, positive=True, args=[], inline=None)

Bases: NiceRepr

Directives modify the runtime state.

classmethod extract(text, directive_re, commands)

Parses directives from a line or repl line

Parameters:

• text (str) – must correspond to exactly one PS1 line and its PS2 followups.

• prefix (str | None) – The directive “namespace”. If None, this uses the xdoctest defaults of DIRECTIVE_RE. This will always be the case for xdoctest, but we are extending this class for use elsewhere.

Yields:

Directive – directive: the parsed directives

_unpack_args(num)

effect(argv=None, environ=None)

effects(argv=None, environ=None)

Returns how this directive modifies a RuntimeState object

This is called by RuntimeState.update() to update itself

Parameters:

• argv (List[str], default=None) – if specified, overwrite sys.argv

• environ (Dict[str, str], default=None) – if specified, overwrite os.environ

Returns:

list of named tuples containing:

action (str): code indicating how to update key (str): name of runtime state item to modify value (object): value to modify with

Return type:

List[Effect]

xcookie.directive._split_opstr(optstr)

Simplified balanced paren logic to only split commas outside of parens

Example

>>> optstr = '+FOO, REQUIRES(foo,bar), +ELLIPSIS'
>>> _split_opstr(optstr)
['+FOO', 'REQUIRES(foo,bar)', '+ELLIPSIS']

xcookie.directive._is_requires_satisfied(arg, argv=None, environ=None)

Determines if the argument to a REQUIRES directive is satisfied

Parameters:

• arg (str) – condition code

• argv (List[str]) – cmdline if arg is cmd code usually sys.argv

• environ (Dict[str, str]) – environment variables usually os.environ

Returns:

flag - True if the requirement is met

Return type:

bool

class xcookie.directive.DirectiveExtractor(namespace, commands)

Bases: object

Example

>>> from xcookie.directive import *  # NOQA
>>> namespace = 'xcookie'
>>> commands = ['UNCOMMENT_IF', 'COMMENT_IF']
>>> self = DirectiveExtractor(namespace, commands)
>>> text = '- this line is not python # xcookie: +COMMENT_IF(cv2)'
>>> text = '# commented line # xcookie: +UNCOMMENT_IF(cv2)'
>>> extracted = self.extract(text)
>>> assert len(extracted) == 1
>>> directive = extracted[0]

extract(text)

xcookie.directive._module_exists(modname)

xcookie.directive.parse_directive_optstr(optpart, commands, inline=None)

Parses the information in the directive from the “optpart”

optstrs are:

optionally prefixed with + (default) or - comma separated may contain one paren enclosed argument (experimental) all spaces are ignored

Returns:

the parsed directive

Return type:

Directive