API Docs¶

Submodules¶

class genie.abstract.decorator.LookupDecorator(*attrs, builder=<function default_builder>, attr_getter=<cyfunction default_token_getter>, **builder_kwargs)¶

Bases: object

This class is to be used as a decorator on class methods in abstracted packages. It allows dynamic class method references: eg, calling obj.b() first performs a lookup on the tokens, and if found, calls the class.b from the actual token matching.

This class is built on the python descriptor mechanism.

Note

This class functions based on the same principles as the AbstractPackage and Lookup() combination. However, instead of using declare_package() at the root of an abstraction package. this decorator treats the calling class’s module as the root of a new abstraction package, and goes from there.

Examples

class MyClass(object):

@LookupDecorator(‘os’) def do_work(self):

pass

Parameters

(list of str) (*attrs) –
(func) (attr_getter) –
(func) –
(kwargs) (**builder_kwargs) – sequence builder.

from_device(**kwargs)¶

lookup_from_device

The actual LookupDecorator.from_device decorator

If decorator is called without arguments (no ()), the method would be the first argument. we need to manually call dunder __call__().

If it is called with arguments, then we need to return the actual decorator that takes in the method.

genie.abstract.decorator.default_token_getter(obj, attrs)¶

default api to be used by the LookupDecorator in order to collect the provided attributes during runtime.

This api first attempts to get obj.<attr>. If not found, attempts to collect from obj.device.<attr>, else raise error.

Parameters

(object) (obj) –
(list of strings) (attrs) –

Returns

Return type

collected attributes

genie.abstract.decorator.from_device_token_getter(obj, defaults=[])¶

default api to be used by the LookupFromDeviceDecorator in order to collect the provided attributes during runtime.

This api first attempts to get attributes from device.custom.abstraction. If not found, falls back to provided defaults.

This api first attempts to get obj.<attr>. If not found, attempts to collect from obj.device.<attr>, else raise error.

Parameters

(object) (obj) –
(list of strings) (attrs) –

Returns

Return type

collected attributes

genie.abstract.decorator.lookup_from_device(*args, **kwargs)¶

The actual LookupDecorator.from_device decorator

If decorator is called without arguments (no ()), the method would be the first argument. we need to manually call dunder __call__().

If it is called with arguments, then we need to return the actual decorator that takes in the method.

genie.abstract.magic.default_builder(tokens, *, mandatory=())¶

A token sequence builder takes in a mandatory list of ‘tokens’ as specified by the user, and any other keyword arguments necessary, and returns the abstraction lookup sequence by combining the tokens into appropriate lookup combinations.

This default builder is a blend between usability and complexity, allowing for token dependencies and mandatory tokens.

Parameters

(list) (tokens) – down from Lookup() class.
(iterable) (mandatory) – they must appear in the lookup sequence.

Returns

Return type

list of tuples

Example

>>> default_builder(['os', 'series', 'type', 'yang', 'release'],
                    mandatory =['yang'])
[('os', 'series', 'type', 'yang', 'release'),
 ('os', 'series', 'type', 'yang'),
 ('os', 'series', 'yang'),
 ('os', 'yang'),
 ('yang',)]

genie.abstract.magic.get_caller_stack_pkgs(stacklvl=1)¶

helper function, returns a dictionary of names/abstraction module based on the caller’s stack frame.

Example

>>> import genie
>>> import mylib as local_lib
>>> get_caller_stack_pkgs()
{'genie': <module genie...>,
 'local_lib': <module mylib...>,}

genie.abstract.magic.DEFAULT_BUILDER(tokens, *, mandatory=())¶

default_builder

A token sequence builder takes in a mandatory list of ‘tokens’ as specified by the user, and any other keyword arguments necessary, and returns the abstraction lookup sequence by combining the tokens into appropriate lookup combinations.

This default builder is a blend between usability and complexity, allowing for token dependencies and mandatory tokens.

Parameters

(list) (tokens) – down from Lookup() class.
(iterable) (mandatory) – they must appear in the lookup sequence.

Returns

Return type

list of tuples

Example

>>> default_builder(['os', 'series', 'type', 'yang', 'release'],
                    mandatory =['yang'])
[('os', 'series', 'type', 'yang', 'release'),
 ('os', 'series', 'type', 'yang'),
 ('os', 'series', 'yang'),
 ('os', 'yang'),
 ('yang',)]

class genie.abstract.magic.Lookup(*tokens, builder=None, packages=None, **builder_kwargs)¶

Bases: object

When instanciated with a set of “token requirements”, the lookup object allows users to dynamically reference libraries (abstraction packages).

The concept is akin to dynamic imports. As opposed to

>>> from genie.nxos import Ospf
>>> from local_lib.nxos.titanium import Blah

lookup allows the user to simply do:

>>> import genie
>>> import local_lib
>>> l = Lookup('nxos', 'titanium')
>>> l.Ospf()
>>> l.Blah()

where the actual import based on the given tokens will be sorted out for the user dynamically.

Parameters

(list of str) (*tokens) –
(func) (builder) –
(dict) (packages) – if not provided, the caller’s stack is looked up for all available abstraction packages.
(kwargs) (**builder_kwargs) – sequence builder.

Examples

>>> import my_abstracted_lib as lib
>>> l = Lookup('nxos', 'titanium')
>>> l.lib.module_a.module_b.MyClass()

classmethod tokens_from_device(device, default_tokens=None, **kwargs)¶

classmethod from_device(device, packages=None, default_tokens=None, **kwargs)¶

creates an abstraction Lookup object by getting the token arguments from a pyATS device objects.

This api expects the device object to have an “abstraction” dictionary under ‘custom’ attribute. Eg:

Example

devices:

my-device:

custom:

abstraction:: order: [os, serie, context] os: nxos serie: n7k context: yang

Parameters

(Device) (device) –
(func) (builder) –
(dict) (packages) – if not provided, the caller’s stack is looked up for all available abstraction packages.
(list) (default_tokens) – from device.
(kwargs) (**builder_kwargs) – sequence builder.

class genie.abstract.magic.AbstractedModule(package, sequence)¶

Bases: object

Internal class, part-two of lookup mechanism. This class is instanciated each time a successful package reference (through Lookup class instances) is done, and tracks internally user’s attribute chain, used as part of the lookup process.

Parameters

(AbstractPackage) (package) –
(list) (sequence) –

class genie.abstract.package.AbstractPackage(obj, delay=False)¶

Bases: object

An abstract package is one where its import paths are two parth: the relative information part, and the tokenization part. With the proper tools, abstract packages allows users to make calls to classes/methods/etc without having to explicitly specify the import/module path, and only use the informational one.

from my_library.nxos.ospf import Ospf

| |

token |

library pkg |
information path

When an abstract package is learnt, all child modules within the given module (if it is a) package, will be loaded recursively in order to build the abstraction matrix/database. Normally this class instance is stored under a var called “__abstract_pkg” on the given module.

Note

A packge is a module that contains other modules.

Parameters

(str/ModuleType) (obj) –
(bool) (delay) – module’s child modules.

learn()¶: recursively learn this package’s child content

property learnt¶: property, returns True if the matrix is not empty (learnt). Otherwise, returns false.

lookup(relpath, tokens, name)¶

property module¶: returns the python module object assoicated with this abstracted package

property paths¶: search paths for this package’s children modules. - if it’s a namespace package, __path__ is a list - else, default to its [__file__, ] - note: could’ve used ModuleSpec (__spec__) instead for python 3.4+

register(relpath, tokens, module)¶

store a module internally with its relative name and token path in the internal matrix.

Parameters

(tuple) (tokens) – (‘a’, ‘b’, ‘c’) for a.b.c
(tuple) –
(ModuleType) (module) –

class genie.abstract.token.AbstractToken(modulename)¶

Bases: object

Describes an arbitrary named token within an abstracted package. Normally this class instance is stored under a var called “__abstract_token” on the given module.

Parameters: (ModuleType) (module) –

property module¶: returns the python module object assoicated with this token

class genie.abstract.token.TokenChain(chain=None)¶

Bases: object

Internal class. Used to track the current chain of tokens in the recursive import process.

Parameters: (list) (chain) –

copy()¶

to_tuple()¶

to_tuples

returns all currently tracked tokens in a tuple. This is needed as the abstracted package uses token tuples as keys for lookup.

track(module)¶

context manager api allowing auto-tracking of tokens using the with statement. On entry, stors the discovered token (if any) internally, on exit, removes that token from tracking.

Parameters: (ModuleType) (module) –

Example

>>> with tokenchain.track(module):
...     pass

API Docs¶

Submodules¶

Module contents¶