class Collection(object):
def __init__(self):
self.tasks = Lexicon()
self.default = None
def add_task(self, name, task, aliases=(), default=False):
"""
Adds callable object ``task`` to this collection under name ``name``.
If ``aliases`` is given, will be used to set up additional aliases for
this task.
``default`` may be set to ``True`` to set the task as this collection's
default invocation.
"""
self.tasks[name] = task
for alias in aliases:
self.tasks.alias(alias, to=name)
if default:
if self.default:
msg = "'%s' cannot be the default because '%s' already is!"
raise ValueError(msg % (name, self.default))
self.default = name
def __getitem__(self, name=None):
"""
Returns task named ``name``. Honors aliases.
If this collection has a default task, it is returned when ``name`` is
empty or ``None``. If empty input is given and no task has been
selected as the default, ValueError will be raised.
"""
if not name:
if self.default:
return self[self.default]
else:
raise ValueError("This collection has no default task.")
return self.tasks[name]
def to_contexts(self):
"""
Returns all contained tasks and subtasks as a list of parser contexts.
"""
result = []
for name, task in self.tasks.iteritems():
context = Context(name=name, aliases=task.aliases)
argspec = task.argspec
for name, default in argspec.iteritems():
# Handle arg options
opts = {}
if default is not None:
opts['kind'] = type(default)
# Handle aliases (auto shortflags, etc)
names = [name]
names.extend(argspec.aliases_of(name))
# Create/add the argument
context.add_arg(names=names, **opts)
result.append(context)
return result
def dir_only_shows_real_keys(self):
"dir() only shows real keys-as-attrs, not aliases"
a = Lexicon({'key1': 'val1', 'key2': 'val2'})
a.alias('myalias', 'key1')
assert 'key1' in dir(a)
assert 'key2' in dir(a)
assert 'myalias' not in dir(a)
def argspec(self):
spec = inspect.getargspec(self.body)
# Associate default values with their respective arg names
if spec.defaults is not None:
ret = Lexicon(zip(spec.args[-len(spec.defaults):], spec.defaults))
else:
ret = Lexicon()
# Pull in args that have no default values
ret.update((x, None) for x in spec.args if x not in ret)
# Handle auto short flags
if self.auto_shortflags:
for name in ret:
alias = None
for char in name:
if not (char == name or char in ret):
alias = char
break
if alias:
ret.alias(alias, to=name)
return ret
class Parser(object):
def __init__(self, contexts=(), initial=None):
self.initial = initial
self.contexts = Lexicon()
for context in contexts:
debug("Adding %s" % context)
if not context.name:
raise ValueError("Non-initial contexts must have names.")
exists = "A context named/aliased %r is already in this parser!"
if context.name in self.contexts:
raise ValueError(exists % context.name)
self.contexts[context.name] = context
for alias in context.aliases:
if alias in self.contexts:
raise ValueError(exists % alias)
self.contexts.alias(alias, to=context.name)
def parse_argv(self, argv):
"""
Parse an argv-style token list ``argv``.
Returns a list of ``Context`` objects matching the order they were
found in the ``argv`` and containing ``Argument`` objects with updated
values based on any flags given.
Assumes any program name has already been stripped out. Good::
Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])
Bad::
Parser(...).parse_argv(['invoke', '--core-opt', ...])
"""
machine = ParseMachine(initial=self.initial, contexts=self.contexts)
for token in argv:
machine.handle(token)
machine.finish()
return machine.result
class Collection(object):
def __init__(self):
self.tasks = Lexicon()
self.default = None
def add_task(self, name, task, aliases=(), default=False):
"""
Adds callable object ``task`` to this collection under name ``name``.
If ``aliases`` is given, will be used to set up additional aliases for
this task.
``default`` may be set to ``True`` to set the task as this collection's
default invocation.
"""
self.tasks[name] = task
for alias in aliases:
self.tasks.alias(alias, to=name)
if default:
if self.default:
msg = "'%s' cannot be the default because '%s' already is!"
raise ValueError(msg % (name, self.default))
self.default = name
def get(self, name=None):
"""
Returns task named ``name``. Honors aliases.
If this collection has a default task, it is returned when ``name`` is
empty or ``None``. If empty input is given and no task has been
selected as the default, ValueError will be raised.
"""
if not name:
if self.default:
return self.get(self.default)
else:
raise ValueError("This collection has no default task.")
return self.tasks[name]
def aliases_work(self):
l = Lexicon()
l.alias('foo', to='bar')
l['bar'] = 'value'
assert l['foo'] == l['bar'] == 'value'
class Parser(object):
"""
Create parser conscious of ``contexts`` and optional ``initial`` context.
``contexts`` should be an iterable of ``Context`` instances which will be
searched when new context names are encountered during a parse. These
Contexts determine what flags may follow them, as well as whether given
flags take values.
``initial`` is optional and will be used to determine validity of "core"
options/flags at the start of the parse run, if any are encountered.
``ignore_unknown`` determines what to do when contexts are found which do
not map to any members of ``contexts``. By default it is ``False``, meaning
any unknown contexts result in a parse error exception. If ``True``,
encountering an unknown context halts parsing and populates the return
value's ``.unparsed`` attribute with the remaining parse tokens.
.. versionadded:: 1.0
"""
def __init__(self, contexts=(), initial=None, ignore_unknown=False):
self.initial = initial
self.contexts = Lexicon()
self.ignore_unknown = ignore_unknown
for context in contexts:
debug("Adding {}".format(context))
if not context.name:
raise ValueError("Non-initial contexts must have names.")
exists = "A context named/aliased {!r} is already in this parser!"
if context.name in self.contexts:
raise ValueError(exists.format(context.name))
self.contexts[context.name] = context
for alias in context.aliases:
if alias in self.contexts:
raise ValueError(exists.format(alias))
self.contexts.alias(alias, to=context.name)
def parse_argv(self, argv):
"""
Parse an argv-style token list ``argv``.
Returns a list (actually a subclass, `.ParseResult`) of
`.ParserContext` objects matching the order they were found in the
``argv`` and containing `.Argument` objects with updated values based
on any flags given.
Assumes any program name has already been stripped out. Good::
Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])
Bad::
Parser(...).parse_argv(['invoke', '--core-opt', ...])
:param argv: List of argument string tokens.
:returns:
A `.ParseResult` (a ``list`` subclass containing some number of
`.ParserContext` objects).
.. versionadded:: 1.0
"""
machine = ParseMachine(
initial=self.initial,
contexts=self.contexts,
ignore_unknown=self.ignore_unknown,
)
# FIXME: Why isn't there str.partition for lists? There must be a
# better way to do this. Split argv around the double-dash remainder
# sentinel.
debug("Starting argv: {!r}".format(argv))
try:
ddash = argv.index("--")
except ValueError:
ddash = len(argv) # No remainder == body gets all
body = argv[:ddash]
remainder = argv[ddash:][1:] # [1:] to strip off remainder itself
if remainder:
debug("Remainder: argv[{!r}:][1:] => {!r}".format(
ddash, remainder))
for index, token in enumerate(body):
# Handle non-space-delimited forms, if not currently expecting a
# flag value and still in valid parsing territory (i.e. not in
# "unknown" state which implies store-only)
# NOTE: we do this in a few steps so we can
# split-then-check-validity; necessary for things like when the
# previously seen flag optionally takes a value.
mutations = []
orig = token
if is_flag(token) and not machine.result.unparsed:
# Equals-sign-delimited flags, eg --foo=bar or -f=bar
if "=" in token:
token, _, value = token.partition("=")
msg = "Splitting x=y expr {!r} into tokens {!r} and {!r}"
debug(msg.format(orig, token, value))
mutations.append((index + 1, value))
# Contiguous boolean short flags, e.g. -qv
elif not is_long_flag(token) and len(token) > 2:
full_token = token[:]
rest, token = token[2:], token[:2]
err = "Splitting {!r} into token {!r} and rest {!r}"
debug(err.format(full_token, token, rest))
# Handle boolean flag block vs short-flag + value. Make
# sure not to test the token as a context flag if we've
# passed into 'storing unknown stuff' territory (e.g. on a
# core-args pass, handling what are going to be task args)
have_flag = (token in machine.context.flags
and machine.current_state != "unknown")
if have_flag and machine.context.flags[token].takes_value:
msg = "{!r} is a flag for current context & it takes a value, giving it {!r}" # noqa
debug(msg.format(token, rest))
mutations.append((index + 1, rest))
else:
rest = ["-{}".format(x) for x in rest]
msg = (
"Splitting multi-flag glob {!r} into {!r} and {!r}"
) # noqa
debug(msg.format(orig, token, rest))
for item in reversed(rest):
mutations.append((index + 1, item))
# Here, we've got some possible mutations queued up, and 'token'
# may have been overwritten as well. Whether we apply those and
# continue as-is, or roll it back, depends:
# - If the parser wasn't waiting for a flag value, we're already on
# the right track, so apply mutations and move along to the
# handle() step.
# - If we ARE waiting for a value, and the flag expecting it ALWAYS
# wants a value (it's not optional), we go back to using the
# original token. (TODO: could reorganize this to avoid the
# sub-parsing in this case, but optimizing for human-facing
# execution isn't critical.)
# - Finally, if we are waiting for a value AND it's optional, we
# inspect the first sub-token/mutation to see if it would otherwise
# have been a valid flag, and let that determine what we do (if
# valid, we apply the mutations; if invalid, we reinstate the
# original token.)
if machine.waiting_for_flag_value:
optional = machine.flag and machine.flag.optional
subtoken_is_valid_flag = token in machine.context.flags
if not (optional and subtoken_is_valid_flag):
token = orig
mutations = []
for index, value in mutations:
body.insert(index, value)
machine.handle(token)
machine.finish()
result = machine.result
result.remainder = " ".join(remainder)
return result
class Collection(object):
"""
A collection of executable tasks.
"""
def __init__(self, *args, **kwargs):
"""
Create a new task collection/namespace.
`.Collection` offers a set of methods for building a collection of
tasks from scratch, plus a convenient constructor wrapping said API.
In either case:
* the first positional argument may be a string, which (if given) is
used as the collection's default name when performing namespace
lookups;
* a ``loaded_from`` keyword argument may be given, which sets metadata
indicating the filesystem path the collection was loaded from. This
is used as a guide when loading per-project :ref:`configuration files
<config-hierarchy>`.
**The method approach**
May initialize with no arguments and use methods (e.g.
`.add_task`/`.add_collection`) to insert objects::
c = Collection()
c.add_task(some_task)
If an initial string argument is given, it is used as the default name
for this collection, should it be inserted into another collection as a
sub-namespace::
docs = Collection('docs')
docs.add_task(doc_task)
ns = Collection()
ns.add_task(top_level_task)
ns.add_collection(docs)
# Valid identifiers are now 'top_level_task' and 'docs.doc_task'
# (assuming the task objects were actually named the same as the
# variables we're using :))
For details, see the API docs for the rest of the class.
**The constructor approach**
All ``*args`` given to `.Collection` (besides the abovementioned
optional positional 'name' argument and ``loaded_from`` kwarg) are
expected to be `.Task` or `.Collection` instances which will be passed
to `.add_task`/`.add_collection` as appropriate. Module objects are
also valid (as they are for `.add_collection`). For example, the below
snippet results in the same two task identifiers as the one above::
ns = Collection(top_level_task, Collection('docs', doc_task))
If any ``**kwargs`` are given, the keywords are used as the initial
name arguments for the respective values::
ns = Collection(
top_level_task=some_other_task,
docs=Collection(doc_task)
)
That's exactly equivalent to::
docs = Collection(doc_task)
ns = Collection()
ns.add_task(some_other_task, 'top_level_task')
ns.add_collection(docs, 'docs')
See individual methods' API docs for details.
"""
# Initialize
self.tasks = Lexicon()
self.collections = Lexicon()
self.default = None
self.name = None
self._configuration = {}
# Name if applicable
args = list(args)
if args and isinstance(args[0], six.string_types):
self.name = args.pop(0)
# Specific kwargs if applicable
self.loaded_from = kwargs.pop('loaded_from', None)
# Dispatch args/kwargs
for arg in args:
self._add_object(arg)
# Dispatch kwargs
for name, obj in six.iteritems(kwargs):
self._add_object(obj, name)
def _add_object(self, obj, name=None):
if isinstance(obj, Task):
method = self.add_task
elif isinstance(obj, (Collection, types.ModuleType)):
method = self.add_collection
else:
raise TypeError("No idea how to insert {0!r}!".format(type(obj)))
return method(obj, name=name)
def __str__(self):
return "<Collection {0!r}: {1}>".format(
self.name, ", ".join(sorted(self.tasks.keys())))
def __repr__(self):
return str(self)
def __eq__(self, other):
return self.name == other.name and self.tasks == other.tasks
@classmethod
def from_module(self, module, name=None, config=None, loaded_from=None):
"""
Return a new `.Collection` created from ``module``.
Inspects ``module`` for any `.Task` instances and adds them to a new
`.Collection`, returning it. If any explicit namespace collections
exist (named ``ns`` or ``namespace``) a copy of that collection object
is preferentially loaded instead.
When the implicit/default collection is generated, it will be named
after the module's ``__name__`` attribute, or its last dotted section
if it's a submodule. (I.e. it should usually map to the actual ``.py``
filename.)
Explicitly given collections will only be given that module-derived
name if they don't already have a valid ``.name`` attribute.
:param str name:
A string, which if given will override any automatically derived
collection name (or name set on the module's root namespace, if it
has one.)
:param dict config:
Used to set config options on the newly created `.Collection`
before returning it (saving you a call to `.configure`.)
If the imported module had a root namespace object, ``config`` is
merged on top of it (i.e. overriding any conflicts.)
:param str loaded_from:
Identical to the same-named kwarg from the regular class
constructor - should be the path where the module was
found.
"""
module_name = module.__name__.split('.')[-1]
# See if the module provides a default NS to use in lieu of creating
# our own collection.
for candidate in ('ns', 'namespace'):
obj = getattr(module, candidate, None)
if obj and isinstance(obj, Collection):
# TODO: make this into Collection.clone() or similar
# Explicitly given name wins over root ns name which wins over
# actual module name.
ret = Collection(name or obj.name or module_name,
loaded_from=loaded_from)
ret.tasks = copy.deepcopy(obj.tasks)
ret.collections = copy.deepcopy(obj.collections)
ret.default = copy.deepcopy(obj.default)
# Explicitly given config wins over root ns config
obj_config = copy.deepcopy(obj._configuration)
if config:
merge_dicts(obj_config, config)
ret._configuration = obj_config
return ret
# Failing that, make our own collection from the module's tasks.
tasks = filter(lambda x: isinstance(x, Task), vars(module).values())
# Again, explicit name wins over implicit one from module path
collection = Collection(name or module_name, loaded_from=loaded_from)
for task in tasks:
collection.add_task(task)
if config:
collection.configure(config)
return collection
def add_task(self, task, name=None, default=None):
"""
Add `.Task` ``task`` to this collection.
:param task: The `.Task` object to add to this collection.
:param name:
Optional string name to bind to (overrides the task's own
self-defined ``name`` attribute and/or any Python identifier (i.e.
``.func_name``.)
:param default: Whether this task should be the collection default.
"""
if name is None:
if task.name:
name = task.name
elif hasattr(task.body, 'func_name'):
name = task.body.func_name
elif hasattr(task.body, '__name__'):
name = task.__name__
else:
raise ValueError("Could not obtain a name for this task!")
if name in self.collections:
raise ValueError(
"Name conflict: this collection has a sub-collection named {0!r} already"
.format(name)) # noqa
self.tasks[name] = task
for alias in task.aliases:
self.tasks.alias(alias, to=name)
if default is True or (default is None and task.is_default):
if self.default:
msg = "'{0}' cannot be the default because '{1}' already is!"
raise ValueError(msg.format(name, self.default))
self.default = name
def add_collection(self, coll, name=None):
"""
Add `.Collection` ``coll`` as a sub-collection of this one.
:param coll: The `.Collection` to add.
:param str name:
The name to attach the collection as. Defaults to the collection's
own internal name.
"""
# Handle module-as-collection
if isinstance(coll, types.ModuleType):
coll = Collection.from_module(coll)
# Ensure we have a name, or die trying
name = name or coll.name
if not name:
raise ValueError("Non-root collections must have a name!")
# Test for conflict
if name in self.tasks:
raise ValueError(
"Name conflict: this collection has a task named {0!r} already"
.format(name)) # noqa
# Insert
self.collections[name] = coll
def split_path(self, path):
"""
Obtain first collection + remainder, of a task path.
E.g. for ``"subcollection.taskname"``, return ``("subcollection",
"taskname")``; for ``"subcollection.nested.taskname"`` return
``("subcollection", "nested.taskname")``, etc.
An empty path becomes simply ``('', '')``.
"""
parts = path.split('.')
coll = parts.pop(0)
rest = '.'.join(parts)
return coll, rest
def __getitem__(self, name=None):
"""
Returns task named ``name``. Honors aliases and subcollections.
If this collection has a default task, it is returned when ``name`` is
empty or ``None``. If empty input is given and no task has been
selected as the default, ValueError will be raised.
Tasks within subcollections should be given in dotted form, e.g.
'foo.bar'. Subcollection default tasks will be returned on the
subcollection's name.
"""
return self.task_with_config(name)[0]
def _task_with_merged_config(self, coll, rest, ours):
task, config = self.collections[coll].task_with_config(rest)
return task, dict(config, **ours)
def task_with_config(self, name):
"""
Return task named ``name`` plus its configuration dict.
E.g. in a deeply nested tree, this method returns the `.Task`, and a
configuration dict created by merging that of this `.Collection` and
any nested `Collections <.Collection>`, up through the one actually
holding the `.Task`.
See `~.Collection.__getitem__` for semantics of the ``name`` argument.
:returns: Two-tuple of (`.Task`, `dict`).
"""
# Our top level configuration
ours = self.configuration()
# Default task for this collection itself
if not name:
if self.default:
return self[self.default], ours
else:
raise ValueError("This collection has no default task.")
# Non-default tasks within subcollections -> recurse (sorta)
if '.' in name:
coll, rest = self.split_path(name)
return self._task_with_merged_config(coll, rest, ours)
# Default task for subcollections (via empty-name lookup)
if name in self.collections:
return self._task_with_merged_config(name, '', ours)
# Regular task lookup
return self.tasks[name], ours
def __contains__(self, name):
try:
self[name]
return True
except KeyError:
return False
def to_contexts(self):
"""
Returns all contained tasks and subtasks as a list of parser contexts.
"""
result = []
for primary, aliases in six.iteritems(self.task_names):
task = self[primary]
result.append(
ParserContext(name=primary,
aliases=aliases,
args=task.get_arguments()))
return result
def subtask_name(self, collection_name, task_name):
return '.'.join([collection_name, task_name])
@property
def task_names(self):
"""
Return all task identifiers for this collection as a dict.
Specifically, a dict with the primary/"real" task names as the key, and
any aliases as a list value.
"""
ret = {}
# Our own tasks get no prefix, just go in as-is: {name: [aliases]}
for name, task in six.iteritems(self.tasks):
ret[name] = task.aliases
# Subcollection tasks get both name + aliases prefixed
for coll_name, coll in six.iteritems(self.collections):
for task_name, aliases in six.iteritems(coll.task_names):
# Cast to list to handle Py3 map() 'map' return value,
# so we can add to it down below if necessary.
aliases = list(
map(lambda x: self.subtask_name(coll_name, x), aliases))
# Tack on collection name to alias list if this task is the
# collection's default.
if coll.default and coll.default == task_name:
aliases += (coll_name, )
ret[self.subtask_name(coll_name, task_name)] = aliases
return ret
def configuration(self, taskpath=None):
"""
Obtain merged configuration values from collection & children.
.. note::
Merging uses ``copy.deepcopy`` to prevent state bleed.
:param taskpath:
(Optional) Task name/path, identical to that used for
`~.Collection.__getitem__` (e.g. may be dotted for nested tasks,
etc.) Used to decide which path to follow in the collection tree
when merging config values.
:returns: A `dict` containing configuration values.
"""
if taskpath is None:
return copy.deepcopy(self._configuration)
return self.task_with_config(taskpath)[1]
def configure(self, options):
"""
(Recursively) merge ``options`` into the current `.configuration`.
Options configured this way will be available to all tasks. It is
recommended to use unique keys to avoid potential clashes with other
config options
For example, if you were configuring a Sphinx docs build target
directory, it's better to use a key like ``'sphinx.target'`` than
simply ``'target'``.
:param options: An object implementing the dictionary protocol.
:returns: ``None``.
"""
merge_dicts(self._configuration, options)
def aliases_appear_in_attributes(self):
l = Lexicon()
l.alias('foo', to='bar')
l.foo = 'value'
assert l.foo == l.bar == l['foo'] == l['bar'] == 'value'
def aliased_real_attributes_do_not_override_real_attributes(self):
lex = Lexicon()
lex.alias('get', to='notget')
lex.notget = 'value'
assert callable(lex.get)
assert lex.get != 'value'
def aliases_work(self):
lex = Lexicon()
lex.alias('foo', to='bar')
lex['bar'] = 'value'
assert lex['foo'] == lex['bar'] == 'value'
class Parser(object):
"""
Create parser conscious of ``contexts`` and optional ``initial`` context.
``contexts`` should be an iterable of ``Context`` instances which will be
searched when new context names are encountered during a parse. These
Contexts determine what flags may follow them, as well as whether given
flags take values.
``initial`` is optional and will be used to determine validity of "core"
options/flags at the start of the parse run, if any are encountered.
``ignore_unknown`` determines what to do when contexts are found which do
not map to any members of ``contexts``. By default it is ``False``, meaning
any unknown contexts result in a parse error exception. If ``True``,
encountering an unknown context halts parsing and populates the return
value's ``.unparsed`` attribute with the remaining parse tokens.
.. versionadded:: 1.0
"""
def __init__(self, contexts=(), initial=None, ignore_unknown=False):
self.initial = initial
self.contexts = Lexicon()
self.ignore_unknown = ignore_unknown
for context in contexts:
debug("Adding {}".format(context))
if not context.name:
raise ValueError("Non-initial contexts must have names.")
exists = "A context named/aliased {!r} is already in this parser!"
if context.name in self.contexts:
raise ValueError(exists.format(context.name))
self.contexts[context.name] = context
for alias in context.aliases:
if alias in self.contexts:
raise ValueError(exists.format(alias))
self.contexts.alias(alias, to=context.name)
def parse_argv(self, argv):
"""
Parse an argv-style token list ``argv``.
Returns a list (actually a subclass, `.ParseResult`) of
`.ParserContext` objects matching the order they were found in the
``argv`` and containing `.Argument` objects with updated values based
on any flags given.
Assumes any program name has already been stripped out. Good::
Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])
Bad::
Parser(...).parse_argv(['invoke', '--core-opt', ...])
:param argv: List of argument string tokens.
:returns:
A `.ParseResult` (a ``list`` subclass containing some number of
`.ParserContext` objects).
.. versionadded:: 1.0
"""
machine = ParseMachine(
initial=self.initial,
contexts=self.contexts,
ignore_unknown=self.ignore_unknown,
)
# FIXME: Why isn't there str.partition for lists? There must be a
# better way to do this. Split argv around the double-dash remainder
# sentinel.
debug("Starting argv: {!r}".format(argv))
try:
ddash = argv.index("--")
except ValueError:
ddash = len(argv) # No remainder == body gets all
body = argv[:ddash]
remainder = argv[ddash:][1:] # [1:] to strip off remainder itself
if remainder:
debug(
"Remainder: argv[{!r}:][1:] => {!r}".format(ddash, remainder)
)
for index, token in enumerate(body):
# Handle non-space-delimited forms, if not currently expecting a
# flag value and still in valid parsing territory (i.e. not in
# "unknown" state which implies store-only)
# NOTE: we do this in a few steps so we can
# split-then-check-validity; necessary for things like when the
# previously seen flag optionally takes a value.
mutations = []
orig = token
if is_flag(token) and not machine.result.unparsed:
# Equals-sign-delimited flags, eg --foo=bar or -f=bar
if "=" in token:
token, _, value = token.partition("=")
msg = "Splitting x=y expr {!r} into tokens {!r} and {!r}"
debug(msg.format(orig, token, value))
mutations.append((index + 1, value))
# Contiguous boolean short flags, e.g. -qv
elif not is_long_flag(token) and len(token) > 2:
full_token = token[:]
rest, token = token[2:], token[:2]
err = "Splitting {!r} into token {!r} and rest {!r}"
debug(err.format(full_token, token, rest))
# Handle boolean flag block vs short-flag + value. Make
# sure not to test the token as a context flag if we've
# passed into 'storing unknown stuff' territory (e.g. on a
# core-args pass, handling what are going to be task args)
have_flag = (
token in machine.context.flags
and machine.current_state != "unknown"
)
if have_flag and machine.context.flags[token].takes_value:
msg = "{!r} is a flag for current context & it takes a value, giving it {!r}" # noqa
debug(msg.format(token, rest))
mutations.append((index + 1, rest))
else:
rest = ["-{}".format(x) for x in rest]
msg = (
"Splitting multi-flag glob {!r} into {!r} and {!r}"
) # noqa
debug(msg.format(orig, token, rest))
for item in reversed(rest):
mutations.append((index + 1, item))
# Here, we've got some possible mutations queued up, and 'token'
# may have been overwritten as well. Whether we apply those and
# continue as-is, or roll it back, depends:
# - If the parser wasn't waiting for a flag value, we're already on
# the right track, so apply mutations and move along to the
# handle() step.
# - If we ARE waiting for a value, and the flag expecting it ALWAYS
# wants a value (it's not optional), we go back to using the
# original token. (TODO: could reorganize this to avoid the
# sub-parsing in this case, but optimizing for human-facing
# execution isn't critical.)
# - Finally, if we are waiting for a value AND it's optional, we
# inspect the first sub-token/mutation to see if it would otherwise
# have been a valid flag, and let that determine what we do (if
# valid, we apply the mutations; if invalid, we reinstate the
# original token.)
if machine.waiting_for_flag_value:
optional = machine.flag and machine.flag.optional
subtoken_is_valid_flag = token in machine.context.flags
if not (optional and subtoken_is_valid_flag):
token = orig
mutations = []
for index, value in mutations:
body.insert(index, value)
machine.handle(token)
machine.finish()
result = machine.result
result.remainder = " ".join(remainder)
return result
class Parser(object):
"""
Create parser conscious of ``contexts`` and optional ``initial`` context.
``contexts`` should be an iterable of ``Context`` instances which will be
searched when new context names are encountered during a parse. These
Contexts determine what flags may follow them, as well as whether given
flags take values.
``initial`` is optional and will be used to determine validity of "core"
options/flags at the start of the parse run, if any are encountered.
``ignore_unknown`` determines what to do when contexts are found which do
not map to any members of ``contexts``. By default it is ``False``, meaning
any unknown contexts result in a parse error exception. If ``True``,
encountering an unknown context halts parsing and populates the return
value's ``.unparsed`` attribute with the remaining parse tokens.
"""
def __init__(self, contexts=(), initial=None, ignore_unknown=False):
self.initial = initial
self.contexts = Lexicon()
self.ignore_unknown = ignore_unknown
for context in contexts:
debug("Adding %s" % context)
if not context.name:
raise ValueError("Non-initial contexts must have names.")
exists = "A context named/aliased %r is already in this parser!"
if context.name in self.contexts:
raise ValueError(exists % context.name)
self.contexts[context.name] = context
for alias in context.aliases:
if alias in self.contexts:
raise ValueError(exists % alias)
self.contexts.alias(alias, to=context.name)
def parse_argv(self, argv):
"""
Parse an argv-style token list ``argv``.
Returns a list of ``Context`` objects matching the order they were
found in the ``argv`` and containing ``Argument`` objects with updated
values based on any flags given.
Assumes any program name has already been stripped out. Good::
Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])
Bad::
Parser(...).parse_argv(['invoke', '--core-opt', ...])
"""
machine = ParseMachine(initial=self.initial, contexts=self.contexts,
ignore_unknown=self.ignore_unknown)
# FIXME: Why isn't there str.partition for lists? There must be a
# better way to do this. Split argv around the double-dash remainder
# sentinel.
debug("Starting argv: %r" % (argv,))
try:
ddash = argv.index('--')
except ValueError:
ddash = len(argv) # No remainder == body gets all
body = argv[:ddash]
remainder = argv[ddash:][1:] # [1:] to strip off remainder itself
if remainder:
debug("Remainder: argv[%r:][1:] => %r" % (ddash, remainder))
for index, token in enumerate(body):
# Handle non-space-delimited forms, if not currently expecting a
# flag value.
if not machine.waiting_for_flag_value and token.startswith('-'):
orig = token
# Equals-sign-delimited flags, eg --foo=bar or -f=bar
if '=' in token:
token, _, value = token.partition('=')
debug("Splitting %r into tokens %r and %r" % (orig, token, value))
body.insert(index + 1, value)
# Contiguous boolean short flags, e.g. -qv
elif not token.startswith('--') and len(token) > 2:
rest, token = token[2:], token[:2]
# Handle boolean flag block vs short-flag + value
have_flag = token in machine.context.flags
if have_flag and machine.context.flags[token].takes_value:
body.insert(index + 1, rest)
else:
rest = map(lambda x: '-%s' % x, rest)
debug("Splitting %r into %r and %r" % (orig, token, rest))
for item in reversed(rest):
body.insert(index + 1, item)
machine.handle(token)
machine.finish()
result = machine.result
result.remainder = ' '.join(remainder)
return result
class AnalizadorDeContexto(object):
"""
Analizando contexto con conocimiento de banderas y su formato.
Generalmente asociado con el programa central o un artefacto.
Cuando se ejecuta a través de un analizador, también se mantendrán los
valores de tiempoej rellenados por el analizador.
.. versionadded:: 1.0
"""
def __init__(self, nombre=None, alias=(), args=()):
"""
Crea un nuevo `` AnalizadorDeContexto llamado ``nombre``,
con ``alias``.
``nombre`` es opcional y debería ser una cadena si se proporciona.
Se usa para diferenciar los objetos AnalizadorDeContexto, y para
usarlos en un Analizador al determinar qué porción de entrada podría
pertenecer a un AnalizadorDeContexto dado.
``alias`` también es opcional y debería ser un iterable que contenga
cadenas. El análisis respetará cualquier alias cuando intente
"encontrar" un contexto dado en su entrada.
Puede dar uno o más ``args``, que es una alternativa rápida a llamar a
``para arg en args: self.agregar_arg (arg)`` después de la inicialización.
"""
self.args = Lexicon()
self.args_posicionales = []
self.banderas = Lexicon()
self.banderas_inversas = {} # No need for Lexicon here
self.nombre = nombre
self.alias = alias
for arg in args:
self.agregar_arg(arg)
def __repr__(self):
alias = ""
if self.alias:
alias = " ({})".format(", ".join(self.alias))
nombre = (" {!r}{}".format(self.nombre, alias)) if self.nombre else ""
args = (": {!r}".format(self.args)) if self.args else ""
return "<analizador/Contexto{}{}>".format(nombre, args)
def agregar_arg(self, *args, **kwargs):
"""
Adds given ``Argumento`` (or constructor args for one) to this contexto.
Agrega el ``Argumento`` dado (o los argumentos del constructor para
uno) a este contexto.
El Argumento en cuestión se agrega a los siguientes atributos de dict:
* ``args``: acceso "normal", es decir, los nombres dados se exponen
directamente como claves.
* ``banderas``: acceso "banderalike", es decir, los nombres dados se
traducen a banderas CLI, p. ej. Se puede acceder a ``"foo"`` a
través de ``banderas['--foo']``.
* ``banderas_inversas``: similar a ``banderas`` pero que contiene solo
las versiones "inversas" de las banderas booleanas que por defecto
son True. Esto permite que el analizador rasarbol, por ejemplo,
``--no-mibandera`` y convertirlo en un valor False para el Argumento
``mibandera``.
.. versionadded:: 1.0
"""
# Normalize
if len(args) == 1 and isinstance(args[0], Argumento):
arg = args[0]
else:
arg = Argumento(*args, **kwargs)
# Restricción de unicidad: sin colisiones de nombres
for nombre in arg.nombres:
if nombre in self.args:
msj = "Intenté agregar un argumento llamado {!r} pero uno ya existe!" # noqa
raise ValueError(msj.format(nombre))
# Nombre utilizado como nombre "principal" para fines de alias
principal = arg.nombres[0] # NOT arg.nombre
self.args[principal] = arg
# Observe las posiciones en un atributo de lista ordenada y distinta
if arg.posicional:
self.args_posicionales.append(arg) # Agregar nombres y nicknombres a banderas, args
self.banderas[a_bandera(principal)] = arg
for nombre in arg.nicknombres:
self.args.alias(nombre, to=principal)
self.banderas.alias(a_bandera(nombre), to=a_bandera(principal))
# Agregar nombre_de_atributo a args, pero no a banderas
if arg.nombre_de_atributo:
self.args.alias(arg.nombre_de_atributo, to=principal)
# Agregar a banderas_inversas si es necesario
if arg.tipo == bool and arg.default is True:
# Invierta aquí el nombre de la bandera 'principal', que será
# una versión discontinua del nombre del argumento principal si
# se produjo una transformación de guión bajo a guión.
nombre_inverso = a_bandera("no-{}".format(principal))
self.banderas_inversas[nombre_inverso] = a_bandera(principal)
@property
def faltan_argumentos_posicionales(self):
return [x for x in self.args_posicionales if x.valor is None]
@property
def como_kwargs(self):
"""
This contexto's arguments' values keyed by their ``.nombre`` attribute.
como kwargs
Los valores de los argumentos de este contexto codificados por su
atributo ``.nombre``.
Da como resultado un dicc adecuado para su uso en contextos de Python,
donde p. Ej. un argumento llamado ``foo-bar`` se vuelve accesible como
``foo_bar``.
.. versionadded:: 1.0
"""
ret = {}
for arg in self.args.valores():
ret[arg.nombre] = arg.valor
return ret
def nombres_para(self, bandera):
# TODO: probablemente debería ser un método en Lexicon/AliasDict
return list(set([bandera] + self.banderas.aliases_of(bandera)))
def ayuda_para(self, bandera):
"""
Devuelve 2-tuplas de ``(bandera-spec, help-string)`` para la ``bandera`` dada.
..versionadded:: 1.0
"""
# Obtener arg obj
if bandera not in self.banderas:
err = "{!r} ¡No es una bandera válida para este contexto! Las banderas válidas son: {!r}" # noqa
raise ValueError(err.format(bandera, self.banderas.claves()))
arg = self.banderas[bandera]
# Determine el tipo de valor esperado, si lo hubiera
valor = {str: "CADENA", int: "INT"}.get(arg.tipo)
# Formatear y listo
full_nombres = []
for nombre in self.nombres_para(bandera):
if valor:
# Las banderas cortas son -f VAL, largos son --foo=VAL
# Cuando es opcional, también, -f [VAL] y --foo[=VAL]
if len(nombre.strip("-")) == 1:
valor_ = ("[{}]".format(valor)) if arg.opcional else valor
valorcadena = " {}".format(valor_)
else:
valorcadena = "={}".format(valor)
if arg.opcional:
valorcadena = "[{}]".format(valorcadena)
else:
# sin valor => booleano
# comprobar la inversa
if nombre in self.banderas_inversas.values():
nombre = "--[no-]{}".format(nombre[2:])
valorcadena = ""
# virar juntos
full_nombres.append(nombre + valorcadena)
nombrecadena = ", ".join(sorted(full_nombres, key=len))
helpcadena = arg.help or ""
return nombrecadena, helpcadena
def help_tuplas(self):
"""
Devuelve el iterable ordenado de las tuplas de ayuda para
todos los Argumentos miembro.
Clasifica así:
* La clasificación general es alfanumérica
* Banderas cortas triunfan sobre banderas largas
* Los argumentos con banderas *only* largas y banderas *no* cortas
vendrán primero.
* Cuando un Argumento tiene varias banderas largas o cortas, se
clasificará utilizando el candidato más favorable (el más bajo
alfabéticamente).
Esto resultará en una lista de ayuda como la siguiente::
--alfa, --zeta # 'alfa' gana
--beta
-a, --query # bandera corta gana
-b, --argh
-c
.. versionadded:: 1.0
"""
# TODO: argumento/bandera API debe cambiar :(
# tener que llamar a una_bandera en el primer nombre de un argumento
# es una tontería.
# ¿Pasar un objeto Argumento a ayuda_para puede requerir cambios
# moderados?
# Transmitir a la lista para garantizar que no sea generador en
# Python 3.
return list(
map(
lambda x: self.ayuda_para(a_bandera(x.nombre)),
sorted(self.banderas.valores(), key=bandera_clave),
)
)
def nombres_de_banderas(self):
"""
Similar a `help_tuplas` pero solo devuelve los nombres de las
banderas, no helpcadena.
Específicamente, todos los nombres de las banderas, aplanados, en
orden aproximado.
.. versionadded:: 1.0
"""
# Regular bandera nombres
banderas = sorted(self.banderas.valores(), key=bandera_clave)
nombres = [self.nombres_para(a_bandera(x.nombre)) for x in banderas]
# Los nombres de las banderas inversas se venden por separado
nombres.append(self.banderas_inversas.keys())
return tuple(itertools.chain.from_iterable(nombres))
class Collection(object):
"""
A collection of executable tasks.
"""
def __init__(self, *args, **kwargs):
"""
Create a new task collection/namespace.
`.Collection` offers a set of methods for building a collection of
tasks from scratch, plus a convenient constructor wrapping said API.
In either case:
* the first positional argument may be a string, which (if given) is
used as the collection's default name when performing namespace
lookups;
* a ``loaded_from`` keyword argument may be given, which sets metadata
indicating the filesystem path the collection was loaded from. This
is used as a guide when loading per-project :ref:`configuration files
<config-hierarchy>`.
**The method approach**
May initialize with no arguments and use methods (e.g.
`.add_task`/`.add_collection`) to insert objects::
c = Collection()
c.add_task(some_task)
If an initial string argument is given, it is used as the default name
for this collection, should it be inserted into another collection as a
sub-namespace::
docs = Collection('docs')
docs.add_task(doc_task)
ns = Collection()
ns.add_task(top_level_task)
ns.add_collection(docs)
# Valid identifiers are now 'top_level_task' and 'docs.doc_task'
# (assuming the task objects were actually named the same as the
# variables we're using :))
For details, see the API docs for the rest of the class.
**The constructor approach**
All ``*args`` given to `.Collection` (besides the abovementioned
optional positional 'name' argument and ``loaded_from`` kwarg) are
expected to be `.Task` or `.Collection` instances which will be passed
to `.add_task`/`.add_collection` as appropriate. Module objects are
also valid (as they are for `.add_collection`). For example, the below
snippet results in the same two task identifiers as the one above::
ns = Collection(top_level_task, Collection('docs', doc_task))
If any ``**kwargs`` are given, the keywords are used as the initial
name arguments for the respective values::
ns = Collection(
top_level_task=some_other_task,
docs=Collection(doc_task)
)
That's exactly equivalent to::
docs = Collection(doc_task)
ns = Collection()
ns.add_task(some_other_task, 'top_level_task')
ns.add_collection(docs, 'docs')
See individual methods' API docs for details.
"""
# Initialize
self.tasks = Lexicon()
self.collections = Lexicon()
self.default = None
self.name = None
self._configuration = {}
# Name if applicable
args = list(args)
if args and isinstance(args[0], six.string_types):
self.name = args.pop(0)
# Specific kwargs if applicable
self.loaded_from = kwargs.pop('loaded_from', None)
# Dispatch args/kwargs
for arg in args:
self._add_object(arg)
# Dispatch kwargs
for name, obj in six.iteritems(kwargs):
self._add_object(obj, name)
def _add_object(self, obj, name=None):
if isinstance(obj, Task):
method = self.add_task
elif isinstance(obj, (Collection, types.ModuleType)):
method = self.add_collection
else:
raise TypeError("No idea how to insert {0!r}!".format(type(obj)))
return method(obj, name=name)
def __repr__(self):
return "<Collection {0!r}: {1}>".format(
self.name,
", ".join(sorted(self.tasks.keys())),
)
def __eq__(self, other):
return self.name == other.name and self.tasks == other.tasks
@classmethod
def from_module(self, module, name=None, config=None, loaded_from=None):
"""
Return a new `.Collection` created from ``module``.
Inspects ``module`` for any `.Task` instances and adds them to a new
`.Collection`, returning it. If any explicit namespace collections
exist (named ``ns`` or ``namespace``) a copy of that collection object
is preferentially loaded instead.
When the implicit/default collection is generated, it will be named
after the module's ``__name__`` attribute, or its last dotted section
if it's a submodule. (I.e. it should usually map to the actual ``.py``
filename.)
Explicitly given collections will only be given that module-derived
name if they don't already have a valid ``.name`` attribute.
:param str name:
A string, which if given will override any automatically derived
collection name (or name set on the module's root namespace, if it
has one.)
:param dict config:
Used to set config options on the newly created `.Collection`
before returning it (saving you a call to `.configure`.)
If the imported module had a root namespace object, ``config`` is
merged on top of it (i.e. overriding any conflicts.)
:param str loaded_from:
Identical to the same-named kwarg from the regular class
constructor - should be the path where the module was
found.
"""
module_name = module.__name__.split('.')[-1]
# See if the module provides a default NS to use in lieu of creating
# our own collection.
for candidate in ('ns', 'namespace'):
obj = getattr(module, candidate, None)
if obj and isinstance(obj, Collection):
# TODO: make this into Collection.clone() or similar
# Explicitly given name wins over root ns name which wins over
# actual module name.
ret = Collection(name or obj.name or module_name,
loaded_from=loaded_from)
ret.tasks = copy.deepcopy(obj.tasks)
ret.collections = copy.deepcopy(obj.collections)
ret.default = copy.deepcopy(obj.default)
# Explicitly given config wins over root ns config
obj_config = copy_dict(obj._configuration)
if config:
merge_dicts(obj_config, config)
ret._configuration = obj_config
return ret
# Failing that, make our own collection from the module's tasks.
tasks = filter(
lambda x: isinstance(x, Task),
vars(module).values()
)
# Again, explicit name wins over implicit one from module path
collection = Collection(name or module_name, loaded_from=loaded_from)
for task in tasks:
collection.add_task(task)
if config:
collection.configure(config)
return collection
def add_task(self, task, name=None, default=None):
"""
Add `.Task` ``task`` to this collection.
:param task: The `.Task` object to add to this collection.
:param name:
Optional string name to bind to (overrides the task's own
self-defined ``name`` attribute and/or any Python identifier (i.e.
``.func_name``.)
:param default: Whether this task should be the collection default.
"""
if name is None:
if task.name:
name = task.name
elif hasattr(task.body, 'func_name'):
name = task.body.func_name
elif hasattr(task.body, '__name__'):
name = task.__name__
else:
raise ValueError("Could not obtain a name for this task!")
if name in self.collections:
raise ValueError("Name conflict: this collection has a sub-collection named {0!r} already".format(name)) # noqa
self.tasks[name] = task
for alias in task.aliases:
self.tasks.alias(alias, to=name)
if default is True or (default is None and task.is_default):
if self.default:
msg = "'{0}' cannot be the default because '{1}' already is!"
raise ValueError(msg.format(name, self.default))
self.default = name
def add_collection(self, coll, name=None):
"""
Add `.Collection` ``coll`` as a sub-collection of this one.
:param coll: The `.Collection` to add.
:param str name:
The name to attach the collection as. Defaults to the collection's
own internal name.
"""
# Handle module-as-collection
if isinstance(coll, types.ModuleType):
coll = Collection.from_module(coll)
# Ensure we have a name, or die trying
name = name or coll.name
if not name:
raise ValueError("Non-root collections must have a name!")
# Test for conflict
if name in self.tasks:
raise ValueError("Name conflict: this collection has a task named {0!r} already".format(name)) # noqa
# Insert
self.collections[name] = coll
def split_path(self, path):
"""
Obtain first collection + remainder, of a task path.
E.g. for ``"subcollection.taskname"``, return ``("subcollection",
"taskname")``; for ``"subcollection.nested.taskname"`` return
``("subcollection", "nested.taskname")``, etc.
An empty path becomes simply ``('', '')``.
"""
parts = path.split('.')
coll = parts.pop(0)
rest = '.'.join(parts)
return coll, rest
def __getitem__(self, name=None):
"""
Returns task named ``name``. Honors aliases and subcollections.
If this collection has a default task, it is returned when ``name`` is
empty or ``None``. If empty input is given and no task has been
selected as the default, ValueError will be raised.
Tasks within subcollections should be given in dotted form, e.g.
'foo.bar'. Subcollection default tasks will be returned on the
subcollection's name.
"""
return self.task_with_config(name)[0]
def _task_with_merged_config(self, coll, rest, ours):
task, config = self.collections[coll].task_with_config(rest)
return task, dict(config, **ours)
def task_with_config(self, name):
"""
Return task named ``name`` plus its configuration dict.
E.g. in a deeply nested tree, this method returns the `.Task`, and a
configuration dict created by merging that of this `.Collection` and
any nested `Collections <.Collection>`, up through the one actually
holding the `.Task`.
See `~.Collection.__getitem__` for semantics of the ``name`` argument.
:returns: Two-tuple of (`.Task`, `dict`).
"""
# Our top level configuration
ours = self.configuration()
# Default task for this collection itself
if not name:
if self.default:
return self[self.default], ours
else:
raise ValueError("This collection has no default task.")
# Non-default tasks within subcollections -> recurse (sorta)
if '.' in name:
coll, rest = self.split_path(name)
return self._task_with_merged_config(coll, rest, ours)
# Default task for subcollections (via empty-name lookup)
if name in self.collections:
return self._task_with_merged_config(name, '', ours)
# Regular task lookup
return self.tasks[name], ours
def __contains__(self, name):
try:
self[name]
return True
except KeyError:
return False
def to_contexts(self):
"""
Returns all contained tasks and subtasks as a list of parser contexts.
"""
result = []
for primary, aliases in six.iteritems(self.task_names):
task = self[primary]
result.append(ParserContext(
name=primary, aliases=aliases, args=task.get_arguments()
))
return result
def subtask_name(self, collection_name, task_name):
return '.'.join([collection_name, task_name])
@property
def task_names(self):
"""
Return all task identifiers for this collection as a dict.
Specifically, a dict with the primary/"real" task names as the key, and
any aliases as a list value.
"""
ret = {}
# Our own tasks get no prefix, just go in as-is: {name: [aliases]}
for name, task in six.iteritems(self.tasks):
ret[name] = task.aliases
# Subcollection tasks get both name + aliases prefixed
for coll_name, coll in six.iteritems(self.collections):
for task_name, aliases in six.iteritems(coll.task_names):
# Cast to list to handle Py3 map() 'map' return value,
# so we can add to it down below if necessary.
aliases = list(map(
lambda x: self.subtask_name(coll_name, x),
aliases
))
# Tack on collection name to alias list if this task is the
# collection's default.
if coll.default and coll.default == task_name:
aliases += (coll_name,)
ret[self.subtask_name(coll_name, task_name)] = aliases
return ret
def configuration(self, taskpath=None):
"""
Obtain merged configuration values from collection & children.
:param taskpath:
(Optional) Task name/path, identical to that used for
`~.Collection.__getitem__` (e.g. may be dotted for nested tasks,
etc.) Used to decide which path to follow in the collection tree
when merging config values.
:returns: A `dict` containing configuration values.
"""
if taskpath is None:
return copy_dict(self._configuration)
return self.task_with_config(taskpath)[1]
def configure(self, options):
"""
(Recursively) merge ``options`` into the current `.configuration`.
Options configured this way will be available to all tasks. It is
recommended to use unique keys to avoid potential clashes with other
config options
For example, if you were configuring a Sphinx docs build target
directory, it's better to use a key like ``'sphinx.target'`` than
simply ``'target'``.
:param options: An object implementing the dictionary protocol.
:returns: ``None``.
"""
merge_dicts(self._configuration, options)
class Context(object):
"""
Parsing context with knowledge of flags & their format.
Generally associated with the core program or a task.
When run through a parser, will also hold runtime values filled in by the
parser.
"""
def __init__(self, name=None, aliases=(), args=()):
"""
Create a new ``Context`` named ``name``, with ``aliases``.
``name`` is optional, and should be a string if given. It's used to
tell Context objects apart, and for use in a Parser when determining
what chunk of input might belong to a given Context.
``aliases`` is also optional and should be an iterable containing
strings. Parsing will honor any aliases when trying to "find" a given
context in its input.
May give one or more ``args``, which is a quick alternative to calling
``for arg in args: self.add_arg(arg)`` after initialization.
"""
self.args = Lexicon()
self.name = name
self.aliases = aliases
for arg in args:
self.add_arg(arg)
def __str__(self):
aliases = (" (%s)" % ', '.join(self.aliases)) if self.aliases else ""
name = (" %s%s" % (self.name, aliases)) if self.name else ""
return "Context%s: %r" % (name, self.args)
def add_arg(self, *args, **kwargs):
"""
Adds given ``Argument`` (or constructor args for one) to this context.
"""
# Normalize
if len(args) == 1 and isinstance(args[0], Argument):
arg = args[0]
else:
arg = Argument(*args, **kwargs)
# Test
for name in arg.names:
if name in self.args:
msg = "Tried to add an argument named %r but one already exists!"
raise ValueError(msg % name)
# Add
main = arg.names[0]
self.args[main] = arg
for name in arg.names[1:]:
self.args.alias(name, to=main)
def has_arg(self, arg):
"""
Is this string (``argv`` list member) a valid flag for this context?
"""
return arg in self.args
def get_arg(self, arg):
try:
return self.args[arg]
except KeyError:
raise ValueError, "Argument %r not found" % arg
class ParserContext(object):
"""
Parsing context with knowledge of flags & their format.
Generally associated with the core program or a task.
When run through a parser, will also hold runtime values filled in by the
parser.
"""
def __init__(self, name=None, aliases=(), args=()):
"""
Create a new ``ParserContext`` named ``name``, with ``aliases``.
``name`` is optional, and should be a string if given. It's used to
tell ParserContext objects apart, and for use in a Parser when
determining what chunk of input might belong to a given ParserContext.
``aliases`` is also optional and should be an iterable containing
strings. Parsing will honor any aliases when trying to "find" a given
context in its input.
May give one or more ``args``, which is a quick alternative to calling
``for arg in args: self.add_arg(arg)`` after initialization.
"""
self.args = Lexicon()
self.positional_args = []
self.flags = Lexicon()
self.inverse_flags = {} # No need for Lexicon here
self.name = name
self.aliases = aliases
for arg in args:
self.add_arg(arg)
def __repr__(self):
aliases = ""
if self.aliases:
aliases = " ({0})".format(', '.join(self.aliases))
name = (" {0!r}{1}".format(self.name, aliases)) if self.name else ""
args = (": {0!r}".format(self.args)) if self.args else ""
return "<parser/Context{0}{1}>".format(name, args)
def add_arg(self, *args, **kwargs):
"""
Adds given ``Argument`` (or constructor args for one) to this context.
The Argument in question is added to the following dict attributes:
* ``args``: "normal" access, i.e. the given names are directly exposed
as keys.
* ``flags``: "flaglike" access, i.e. the given names are translated
into CLI flags, e.g. ``"foo"`` is accessible via ``flags['--foo']``.
* ``inverse_flags``: similar to ``flags`` but containing only the
"inverse" versions of boolean flags which default to True. This
allows the parser to track e.g. ``--no-myflag`` and turn it into a
False value for the ``myflag`` Argument.
"""
# Normalize
if len(args) == 1 and isinstance(args[0], Argument):
arg = args[0]
else:
arg = Argument(*args, **kwargs)
# Uniqueness constraint: no name collisions
for name in arg.names:
if name in self.args:
msg = "Tried to add an argument named {0!r} but one already exists!" # noqa
raise ValueError(msg.format(name))
# First name used as "main" name for purposes of aliasing
main = arg.names[0] # NOT arg.name
self.args[main] = arg
# Note positionals in distinct, ordered list attribute
if arg.positional:
self.positional_args.append(arg)
# Add names & nicknames to flags, args
self.flags[to_flag(main)] = arg
for name in arg.nicknames:
self.args.alias(name, to=main)
self.flags.alias(to_flag(name), to=to_flag(main))
# Add attr_name to args, but not flags
if arg.attr_name:
self.args.alias(arg.attr_name, to=main)
# Add to inverse_flags if required
if arg.kind == bool and arg.default is True:
# Invert the 'main' flag name here, which will be a dashed version
# of the primary argument name if underscore-to-dash transformation
# occurred.
inverse_name = to_flag("no-{0}".format(main))
self.inverse_flags[inverse_name] = to_flag(main)
@property
def needs_positional_arg(self):
return any(x.value is None for x in self.positional_args)
@property
def as_kwargs(self):
"""
This context's arguments' values keyed by their ``.name`` attribute.
Results in a dict suitable for use in Python contexts, where e.g. an
arg named ``foo-bar`` becomes accessible as ``foo_bar``.
"""
ret = {}
for arg in self.args.values():
ret[arg.name] = arg.value
return ret
def names_for(self, flag):
# TODO: should probably be a method on Lexicon/AliasDict
return list(set([flag] + self.flags.aliases_of(flag)))
def help_for(self, flag):
"""
Return 2-tuple of ``(flag-spec, help-string)`` for given ``flag``.
"""
# Obtain arg obj
if flag not in self.flags:
err = "{0!r} is not a valid flag for this context! Valid flags are: {1!r}" # noqa
raise ValueError(err.format(flag, self.flags.keys()))
arg = self.flags[flag]
# Determine expected value type, if any
value = {
str: 'STRING',
}.get(arg.kind)
# Format & go
full_names = []
for name in self.names_for(flag):
if value:
# Short flags are -f VAL, long are --foo=VAL
# When optional, also, -f [VAL] and --foo[=VAL]
if len(name.strip('-')) == 1:
value_ = ("[{0}]".format(value)) if arg.optional else value
valuestr = " {0}".format(value_)
else:
valuestr = "={0}".format(value)
if arg.optional:
valuestr = "[{0}]".format(valuestr)
else:
# no value => boolean
# check for inverse
if name in self.inverse_flags.values():
name = "--[no-]{0}".format(name[2:])
valuestr = ""
# Tack together
full_names.append(name + valuestr)
namestr = ", ".join(sorted(full_names, key=len))
helpstr = arg.help or ""
return namestr, helpstr
def help_tuples(self):
"""
Return sorted iterable of help tuples for all member Arguments.
Sorts like so:
* General sort is alphanumerically
* Short flags win over long flags
* Arguments with *only* long flags and *no* short flags will come
first.
* When an Argument has multiple long or short flags, it will sort using
the most favorable (lowest alphabetically) candidate.
This will result in a help list like so::
--alpha, --zeta # 'alpha' wins
--beta
-a, --query # short flag wins
-b, --argh
-c
"""
# TODO: argument/flag API must change :(
# having to call to_flag on 1st name of an Argument is just dumb.
# To pass in an Argument object to help_for may require moderate
# changes?
# Cast to list to ensure non-generator on Python 3.
return list(map(
lambda x: self.help_for(to_flag(x.name)),
sorted(self.flags.values(), key=flag_key)
))
def flag_names(self):
"""
Similar to `help_tuples` but returns flag names only, no helpstrs.
Specifically, all flag names, flattened, in rough order.
"""
# Regular flag names
flags = sorted(self.flags.values(), key=flag_key)
names = [self.names_for(to_flag(x.name)) for x in flags]
# Inverse flag names sold separately
names.append(self.inverse_flags.keys())
return tuple(itertools.chain.from_iterable(names))
class Context(object):
"""
Parsing context with knowledge of flags & their format.
Generally associated with the core program or a task.
When run through a parser, will also hold runtime values filled in by the
parser.
"""
def __init__(self, name=None, aliases=(), args=()):
"""
Create a new ``Context`` named ``name``, with ``aliases``.
``name`` is optional, and should be a string if given. It's used to
tell Context objects apart, and for use in a Parser when determining
what chunk of input might belong to a given Context.
``aliases`` is also optional and should be an iterable containing
strings. Parsing will honor any aliases when trying to "find" a given
context in its input.
May give one or more ``args``, which is a quick alternative to calling
``for arg in args: self.add_arg(arg)`` after initialization.
"""
self.args = Lexicon()
self.flags = Lexicon()
self.name = name
self.aliases = aliases
for arg in args:
self.add_arg(arg)
def __str__(self):
aliases = (" (%s)" % ', '.join(self.aliases)) if self.aliases else ""
name = (" %s%s" % (self.name, aliases)) if self.name else ""
return "Context%s: %r" % (name, self.args)
def add_arg(self, *args, **kwargs):
"""
Adds given ``Argument`` (or constructor args for one) to this context.
The Argument in question is added to two dict attributes:
* ``args``: "normal" access, i.e. the given names are directly exposed
as keys.
* ``flags``: "flaglike" access, i.e. the given names are translated
into CLI flags, e.g. ``"foo"`` is accessible via ``flags['--foo']``.
"""
# Normalize
if len(args) == 1 and isinstance(args[0], Argument):
arg = args[0]
else:
arg = Argument(*args, **kwargs)
# Test
for name in arg.names:
if name in self.args:
msg = "Tried to add an argument named %r but one already exists!"
raise ValueError(msg % name)
# Add
main = arg.names[0]
self.args[main] = arg
self.flags[to_flag(main)] = arg
for name in arg.names[1:]:
self.args.alias(name, to=main)
self.flags.alias(to_flag(name), to=to_flag(main))
def aliases_appear_in_attributes(self):
l = Lexicon()
l.alias('foo', to='bar')
l.foo = 'value'
assert l.foo == l.bar == l['foo'] == l['bar'] == 'value'
class ParserContext(object):
"""
Parsing context with knowledge of flags & their format.
Generally associated with the core program or a task.
When run through a parser, will also hold runtime values filled in by the
parser.
.. versionadded:: 1.0
"""
def __init__(self, name=None, aliases=(), args=()):
"""
Create a new ``ParserContext`` named ``name``, with ``aliases``.
``name`` is optional, and should be a string if given. It's used to
tell ParserContext objects apart, and for use in a Parser when
determining what chunk of input might belong to a given ParserContext.
``aliases`` is also optional and should be an iterable containing
strings. Parsing will honor any aliases when trying to "find" a given
context in its input.
May give one or more ``args``, which is a quick alternative to calling
``for arg in args: self.add_arg(arg)`` after initialization.
"""
self.args = Lexicon()
self.positional_args = []
self.flags = Lexicon()
self.inverse_flags = {} # No need for Lexicon here
self.name = name
self.aliases = aliases
for arg in args:
self.add_arg(arg)
def __repr__(self):
aliases = ""
if self.aliases:
aliases = " ({})".format(', '.join(self.aliases))
name = (" {!r}{}".format(self.name, aliases)) if self.name else ""
args = (": {!r}".format(self.args)) if self.args else ""
return "<parser/Context{}{}>".format(name, args)
def add_arg(self, *args, **kwargs):
"""
Adds given ``Argument`` (or constructor args for one) to this context.
The Argument in question is added to the following dict attributes:
* ``args``: "normal" access, i.e. the given names are directly exposed
as keys.
* ``flags``: "flaglike" access, i.e. the given names are translated
into CLI flags, e.g. ``"foo"`` is accessible via ``flags['--foo']``.
* ``inverse_flags``: similar to ``flags`` but containing only the
"inverse" versions of boolean flags which default to True. This
allows the parser to track e.g. ``--no-myflag`` and turn it into a
False value for the ``myflag`` Argument.
.. versionadded:: 1.0
"""
# Normalize
if len(args) == 1 and isinstance(args[0], Argument):
arg = args[0]
else:
arg = Argument(*args, **kwargs)
# Uniqueness constraint: no name collisions
for name in arg.names:
if name in self.args:
msg = "Tried to add an argument named {!r} but one already exists!" # noqa
raise ValueError(msg.format(name))
# First name used as "main" name for purposes of aliasing
main = arg.names[0] # NOT arg.name
self.args[main] = arg
# Note positionals in distinct, ordered list attribute
if arg.positional:
self.positional_args.append(arg)
# Add names & nicknames to flags, args
self.flags[to_flag(main)] = arg
for name in arg.nicknames:
self.args.alias(name, to=main)
self.flags.alias(to_flag(name), to=to_flag(main))
# Add attr_name to args, but not flags
if arg.attr_name:
self.args.alias(arg.attr_name, to=main)
# Add to inverse_flags if required
if arg.kind == bool and arg.default is True:
# Invert the 'main' flag name here, which will be a dashed version
# of the primary argument name if underscore-to-dash transformation
# occurred.
inverse_name = to_flag("no-{}".format(main))
self.inverse_flags[inverse_name] = to_flag(main)
@property
def missing_positional_args(self):
return [x for x in self.positional_args if x.value is None]
@property
def as_kwargs(self):
"""
This context's arguments' values keyed by their ``.name`` attribute.
Results in a dict suitable for use in Python contexts, where e.g. an
arg named ``foo-bar`` becomes accessible as ``foo_bar``.
.. versionadded:: 1.0
"""
ret = {}
for arg in self.args.values():
ret[arg.name] = arg.value
return ret
def names_for(self, flag):
# TODO: should probably be a method on Lexicon/AliasDict
return list(set([flag] + self.flags.aliases_of(flag)))
def help_for(self, flag):
"""
Return 2-tuple of ``(flag-spec, help-string)`` for given ``flag``.
.. versionadded:: 1.0
"""
# Obtain arg obj
if flag not in self.flags:
err = "{!r} is not a valid flag for this context! Valid flags are: {!r}" # noqa
raise ValueError(err.format(flag, self.flags.keys()))
arg = self.flags[flag]
# Determine expected value type, if any
value = {
str: 'STRING',
int: 'INT',
}.get(arg.kind)
# Format & go
full_names = []
for name in self.names_for(flag):
if value:
# Short flags are -f VAL, long are --foo=VAL
# When optional, also, -f [VAL] and --foo[=VAL]
if len(name.strip('-')) == 1:
value_ = ("[{}]".format(value)) if arg.optional else value
valuestr = " {}".format(value_)
else:
valuestr = "={}".format(value)
if arg.optional:
valuestr = "[{}]".format(valuestr)
else:
# no value => boolean
# check for inverse
if name in self.inverse_flags.values():
name = "--[no-]{}".format(name[2:])
valuestr = ""
# Tack together
full_names.append(name + valuestr)
namestr = ", ".join(sorted(full_names, key=len))
helpstr = arg.help or ""
return namestr, helpstr
def help_tuples(self):
"""
Return sorted iterable of help tuples for all member Arguments.
Sorts like so:
* General sort is alphanumerically
* Short flags win over long flags
* Arguments with *only* long flags and *no* short flags will come
first.
* When an Argument has multiple long or short flags, it will sort using
the most favorable (lowest alphabetically) candidate.
This will result in a help list like so::
--alpha, --zeta # 'alpha' wins
--beta
-a, --query # short flag wins
-b, --argh
-c
.. versionadded:: 1.0
"""
# TODO: argument/flag API must change :(
# having to call to_flag on 1st name of an Argument is just dumb.
# To pass in an Argument object to help_for may require moderate
# changes?
# Cast to list to ensure non-generator on Python 3.
return list(map(
lambda x: self.help_for(to_flag(x.name)),
sorted(self.flags.values(), key=flag_key)
))
def flag_names(self):
"""
Similar to `help_tuples` but returns flag names only, no helpstrs.
Specifically, all flag names, flattened, in rough order.
.. versionadded:: 1.0
"""
# Regular flag names
flags = sorted(self.flags.values(), key=flag_key)
names = [self.names_for(to_flag(x.name)) for x in flags]
# Inverse flag names sold separately
names.append(self.inverse_flags.keys())
return tuple(itertools.chain.from_iterable(names))
class Parser(object):
"""
Create parser conscious of ``contexts`` and optional ``initial`` context.
``contexts`` should be an iterable of ``Context`` instances which will be
searched when new context names are encountered during a parse. These
Contexts determine what flags may follow them, as well as whether given
flags take values.
``initial`` is optional and will be used to determine validity of "core"
options/flags at the start of the parse run, if any are encountered.
``ignore_unknown`` determines what to do when contexts are found which do
not map to any members of ``contexts``. By default it is ``False``, meaning
any unknown contexts result in a parse error exception. If ``True``,
encountering an unknown context halts parsing and populates the return
value's ``.unparsed`` attribute with the remaining parse tokens.
"""
def __init__(self, contexts=(), initial=None, ignore_unknown=False):
self.initial = initial
self.contexts = Lexicon()
self.ignore_unknown = ignore_unknown
for context in contexts:
debug("Adding {0}".format(context))
if not context.name:
raise ValueError("Non-initial contexts must have names.")
exists = "A context named/aliased {0!r} is already in this parser!"
if context.name in self.contexts:
raise ValueError(exists.format(context.name))
self.contexts[context.name] = context
for alias in context.aliases:
if alias in self.contexts:
raise ValueError(exists.format(alias))
self.contexts.alias(alias, to=context.name)
def parse_argv(self, argv):
"""
Parse an argv-style token list ``argv``.
Returns a list of ``Context`` objects matching the order they were
found in the ``argv`` and containing ``Argument`` objects with updated
values based on any flags given.
Assumes any program name has already been stripped out. Good::
Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])
Bad::
Parser(...).parse_argv(['invoke', '--core-opt', ...])
"""
machine = ParseMachine(initial=self.initial, contexts=self.contexts,
ignore_unknown=self.ignore_unknown)
# FIXME: Why isn't there str.partition for lists? There must be a
# better way to do this. Split argv around the double-dash remainder
# sentinel.
debug("Starting argv: {0!r}".format(argv,))
try:
ddash = argv.index('--')
except ValueError:
ddash = len(argv) # No remainder == body gets all
body = argv[:ddash]
remainder = argv[ddash:][1:] # [1:] to strip off remainder itself
if remainder:
debug("Remainder: argv[{0!r}:][1:] => {1!r}".format(
ddash, remainder
))
for index, token in enumerate(body):
# Handle non-space-delimited forms, if not currently expecting a
# flag value and still in valid parsing territory (i.e. not in
# "unknown" state which implies store-only)
if not machine.waiting_for_flag_value and is_flag(token) \
and not machine.result.unparsed:
orig = token
# Equals-sign-delimited flags, eg --foo=bar or -f=bar
if '=' in token:
token, _, value = token.partition('=')
debug("Splitting x=y expr {0!r} into tokens {1!r} and {2!r}".format( # noqa
orig, token, value))
body.insert(index + 1, value)
# Contiguous boolean short flags, e.g. -qv
elif not is_long_flag(token) and len(token) > 2:
full_token = token[:]
rest, token = token[2:], token[:2]
err = "Splitting {0!r} into token {1!r} and rest {2!r}"
debug(err.format(full_token, token, rest))
# Handle boolean flag block vs short-flag + value. Make
# sure not to test the token as a context flag if we've
# passed into 'storing unknown stuff' territory (e.g. on a
# core-args pass, handling what are going to be task args)
have_flag = (token in machine.context.flags
and machine.current_state != 'unknown')
if have_flag and machine.context.flags[token].takes_value:
debug("{0!r} is a flag for current context & it takes a value, giving it {1!r}".format(token, rest)) # noqa
body.insert(index + 1, rest)
else:
rest = ['-{0}'.format(x) for x in rest]
debug("Splitting multi-flag glob {0!r} into {1!r} and {2!r}".format( # noqa
orig, token, rest))
for item in reversed(rest):
body.insert(index + 1, item)
machine.handle(token)
machine.finish()
result = machine.result
result.remainder = ' '.join(remainder)
return result
def aliases_appear_in_attributes(self):
lex = Lexicon()
lex.alias('foo', to='bar')
lex.foo = 'value'
assert lex.foo == lex.bar == lex['foo'] == lex['bar'] == 'value'
class Parser(object):
"""
Create parser conscious of ``contexts`` and optional ``initial`` context.
``contexts`` should be an iterable of ``Context`` instances which will be
searched when new context names are encountered during a parse. These
Contexts determine what flags may follow them, as well as whether given
flags take values.
``initial`` is optional and will be used to determine validity of "core"
options/flags at the start of the parse run, if any are encountered.
``ignore_unknown`` determines what to do when contexts are found which do
not map to any members of ``contexts``. By default it is ``False``, meaning
any unknown contexts result in a parse error exception. If ``True``,
encountering an unknown context halts parsing and populates the return
value's ``.unparsed`` attribute with the remaining parse tokens.
"""
def __init__(self, contexts=(), initial=None, ignore_unknown=False):
self.initial = initial
self.contexts = Lexicon()
self.ignore_unknown = ignore_unknown
for context in contexts:
debug("Adding {}".format(context))
if not context.name:
raise ValueError("Non-initial contexts must have names.")
exists = "A context named/aliased {!r} is already in this parser!"
if context.name in self.contexts:
raise ValueError(exists.format(context.name))
self.contexts[context.name] = context
for alias in context.aliases:
if alias in self.contexts:
raise ValueError(exists.format(alias))
self.contexts.alias(alias, to=context.name)
def parse_argv(self, argv):
"""
Parse an argv-style token list ``argv``.
Returns a list of ``Context`` objects matching the order they were
found in the ``argv`` and containing ``Argument`` objects with updated
values based on any flags given.
Assumes any program name has already been stripped out. Good::
Parser(...).parse_argv(['--core-opt', 'task', '--task-opt'])
Bad::
Parser(...).parse_argv(['invoke', '--core-opt', ...])
"""
machine = ParseMachine(initial=self.initial,
contexts=self.contexts,
ignore_unknown=self.ignore_unknown)
# FIXME: Why isn't there str.partition for lists? There must be a
# better way to do this. Split argv around the double-dash remainder
# sentinel.
debug("Starting argv: {!r}".format(argv, ))
try:
ddash = argv.index('--')
except ValueError:
ddash = len(argv) # No remainder == body gets all
body = argv[:ddash]
remainder = argv[ddash:][1:] # [1:] to strip off remainder itself
if remainder:
debug("Remainder: argv[{!r}:][1:] => {!r}".format(
ddash, remainder))
for index, token in enumerate(body):
# Handle non-space-delimited forms, if not currently expecting a
# flag value and still in valid parsing territory (i.e. not in
# "unknown" state which implies store-only)
if (not machine.waiting_for_flag_value and is_flag(token)
and not machine.result.unparsed):
orig = token
# Equals-sign-delimited flags, eg --foo=bar or -f=bar
if '=' in token:
token, _, value = token.partition('=')
debug("Splitting x=y expr {!r} into tokens {!r} and {!r}".
format( # noqa
orig, token, value))
body.insert(index + 1, value)
# Contiguous boolean short flags, e.g. -qv
elif not is_long_flag(token) and len(token) > 2:
full_token = token[:]
rest, token = token[2:], token[:2]
err = "Splitting {!r} into token {!r} and rest {!r}"
debug(err.format(full_token, token, rest))
# Handle boolean flag block vs short-flag + value. Make
# sure not to test the token as a context flag if we've
# passed into 'storing unknown stuff' territory (e.g. on a
# core-args pass, handling what are going to be task args)
have_flag = (token in machine.context.flags
and machine.current_state != 'unknown')
if have_flag and machine.context.flags[token].takes_value:
debug(
"{!r} is a flag for current context & it takes a value, giving it {!r}"
.format(token, rest)) # noqa
body.insert(index + 1, rest)
else:
rest = ['-{}'.format(x) for x in rest]
debug(
"Splitting multi-flag glob {!r} into {!r} and {!r}"
.format( # noqa
orig, token, rest))
for item in reversed(rest):
body.insert(index + 1, item)
machine.handle(token)
machine.finish()
result = machine.result
result.remainder = ' '.join(remainder)
return result
class Analizador(object):
"""
Crear un analizador consciente de ``contextos`` y un contexto opcional
``inicial``.
``contextos`` debe ser un iterable de instancias de ``Contexto`` que se
buscarán cuando se encuentren nuevos nombres de contexto durante un
análisis. Estos contextos determinan qué banderas pueden seguirlos, así
como si las banderas dadas toman valores.
``inicial`` es opcional y se usará para determinar la validez de las
opciones/banderas del "núcleo" al inicio de la ejecución del análisis,
si se encuentran.
``ignorar_desconocido`` determina qué hacer cuando se encuentran contextos
que no se asignan a ningún miembro de ``contextos``. Por defecto es
``False``, lo que significa que cualquier contexto desconocido resulta en
una excepción de error de análisis. Si es ``True``, encontrar un contexto
desconocido detiene el análisis y llena el atributo ``.sin_analizar`` del
valor de retorno con los tokens de análisis restantes.
.. versionadded:: 1.0
"""
def __init__(self, contextos=(), inicial=None, ignorar_desconocido=False):
self.inicial = inicial
self.contextos = Lexicon()
self.ignorar_desconocido = ignorar_desconocido
for contexto in contextos:
debug("Añadiendo {}".format(contexto))
if not contexto.nombre:
raise ValueError(
"Los contextos no-iniciales deben tener nombres.")
exists = "Un contexto llamado/alias {!r} ya esta en este analizador!"
if contexto.nombre in self.contextos:
raise ValueError(exists.format(contexto.nombre))
self.contextos[contexto.nombre] = contexto
for alias in contexto.alias:
if alias in self.contextos:
raise ValueError(exists.format(alias))
self.contextos.alias(alias, to=contexto.nombre)
def analizar_args(self, argv):
"""
Analiza una lista de tokens de estilo argv ``argv``.
Devuelve una lista (en realidad una subclase, `.AnalizaResultado`) de
objetos `.AnalizadorDeContexto` que coinciden con el orden en que se
encontraron en el ``argv`` y que contienen objetos `.Argumento` con
valores actualizados basados en cualquier bandera dada.
Supone que ya se ha eliminado cualquier nombre de programa. Bueno::
Analizador(...).analizar_args(['--nucleo-opc', 'artefacto', '--artefacto-opc'])
Bad::
Analizador(...).analizar_args(['dued', '--nucleo-opc', ...])
:param argv: Lista de tokens de cadenas de argumentos.
:returns:
Un `.AnalizaResultado` (una subclase de ``list`` que contiene
cierto número de objetos `.AnalizadorDeContexto`)
.. versionadded:: 1.0
"""
machine = AnalizarLaMaquina(
inicial=self.inicial,
contextos=self.contextos,
ignorar_desconocido=self.ignorar_desconocido,
)
# FIXME: ¿Por qué no hay str.partition para las listas? Debe haber
# una mejor manera de hacer esto. Divida argv alrededor del centinela
# restante de dos guiones.
debug("Arrancando argv: {!r}".format(argv))
try:
guion = argv.indice("--")
except ValueError:
guion = len(argv) # Sin resto == cuerpo se queda todo
cuerpo = argv[:guion]
remanente = argv[guion:][1:] # [1:] para quitarse el resto
if remanente:
debug("Remanente[{!r}:][1:] => {!r}".format(guion, remanente))
for indice, token in enumerate(cuerpo):
# Manejar formularios no-delimitados-por-espacios, si no espera
# actualmente un valor de bandera y aún se encuentra en un
# territorio de análisis válido (es decir, no en un estado
# "desconocido" que implica solo-almacenar)
# NOTE: hacemos esto en unos pocos pasos para poder dividir-y
# luego-verificar-la-validez; necesaria para cosas como cuando
# la bandera vista anteriormente toma opcionalmente un valor.
mutaciones = []
orig = token
if es_bandera(token) and not machine.resultado.sin_analizar:
# Banderas delimitadas por signo igual, por ejemplo,
# --foo=bar o -f=bar
if "=" in token:
token, _, valor = token.partition("=")
msj = "Dividiendo x=y expr {!r} en los tokens {!r} y {!r}"
debug(msj.format(orig, token, valor))
mutaciones.append((indice + 1, valor))
# Contiguous booleano short banderas, e.g. -qv
elif not es_bandera_larga(token) and len(token) > 2:
full_token = token[:]
resto, token = token[2:], token[:2]
err = "Dividiendo {!r} en el token {!r} y resto {!r}"
debug(err.format(full_token, token, resto))
# Manejar bloque de bandera booleana vs valor + bandera
# corta. Asegúrese de no probar el token como una bandera
# de contexto si hemos pasado al territorio de 'almacenar
# cosas desconocidas' (por ejemplo, en un pase de
# args-nucleo, manejando lo que van a ser argumentos de
# artefacto)
tiene_bandera = (token in machine.contexto.banderas and
machine.current_state != "desconocido")
if tiene_bandera and machine.contexto.banderas[
token].toma_valor:
msj = "{!r} es una bandera para el contexto actual y toma un valor, dándole {!r}" # noqa
debug(msj.format(token, resto))
mutaciones.append((indice + 1, resto))
else:
resto = ["-{}".format(x) for x in resto]
msj = (
"Didicion global multi-banderas {!r} en {!r} y {!r}"
) # noqa
debug(msj.format(orig, token, resto))
for item in reversed(resto):
mutaciones.append((indice + 1, item))
# Aquí, tenemos algunas posibles mutaciones en cola, y es posible
# que 'token' también se haya sobrescrito. Si los aplicamos y
# continuamos tal como están, o lo revertimos, depende de:
# - Si el analizador no estaba esperando un valor de bandera,
# ya estamos en el camino correcto, así que aplique mutaciones
# y muévase al paso manejar().
# - Si ESTAMOS esperando un valor, y la bandera que lo espera
# SIEMPRE quiere un valor (no es opcional), volvemos a usar el
# token original. (TODO: podría reorganizar esto para evitar el
# subanálisis en este caso, pero la optimización para la
# ejecución dirigida a humanos no es fundamental).
# - Finalmente, si estamos esperando un valor Y es opcional,
# inspeccionamos el primer sub-token/mutación para ver si de
# otra manera hubiera sido un indicador válido, y dejamos que
# eso determine lo que hacemos (si es válido, aplicamos las
# mutaciones; si no es válido, restablecemos el token original).
if machine.esperando_valor_de_bandera:
opcional = machine.bandera and machine.bandera.opcional
subtoken_es_una_bandera_valida = token in machine.contexto.banderas
if not (opcional and subtoken_es_una_bandera_valida):
token = orig
mutaciones = []
for indice, valor in mutaciones:
cuerpo.insert(indice, valor)
machine.manejar(token)
machine.finish()
resultado = machine.resultado
resultado.remanente = " ".join(remanente)
return resultado
def aliases_work(self):
l = Lexicon()
l.alias('foo', to='bar')
l['bar'] = 'value'
assert l['foo'] == l['bar'] == 'value'
