Module codetricks

is a decorator that adds a "buildDocsForThis" attribute to its argument.

This attribute is evaluated by documentation generators.

returns a function resolving classes deriving from baseClass in the sequence objects by their names.

This is used to build registries of Macros and RowProcessors. The classes in question have to have a name attribute.

objects would usually be something like globals().values()

If instances is True the function will return instances instead of classes.

key is a function taking an object and returning the key under which you will later access it. If this function returns None, the object will not be entered into the registry.

returns RST-formatted docs for docItems.

docItems is a list of (title, doc) tuples. doc is currently rendered in a preformatted block.

prints hopefully RST-formatted docs for all subclasses of baseClass in objects.

The function returns True if it finds arguments it expects ("docs" and optionally a char to build underlines from) in the command line, False if not (and it doesn't print anything in this case) if not.

Thus, you'll usually use it like this:

       if __name__=="__main__":        
               if not makeClassDocs(Macro, globals().values()):
                       _test()

a context manager to temporarily redirect stdout to /dev/null.

This is used to shut up some versions of pyparsing and pyfits that insist on spewing stuff to stdout from deep within in relatively normal situations.

Note that this will acquire a lock while things are silenced; this means that silenced things cannot run concurrently.

Decorators:

• @contextlib.contextmanager

executes the controlled block within destDir and then returns to the previous directory.

Think "within dir". Haha.

Decorators:

• @contextlib.contextmanager

sets up and tears down a sandbox directory within tmpdir.

This is is a context manager. The object returned is the original path (which allows you to copy stuff from there). The working directory is the sandbox created while in the controlled block.

If tmpdir is None, the *system* default is used (usually /tmp), rather than dachs' tmpdir. So, you will ususally want to call this as sandbox(base.getConfig("tempDir"))

This is obviously not thread-safe -- you'll not usually want to run this in the main server process. Better fork before running this.

You can pass in a function extractfunc(owd) that is executed in the sandbox just before teardown. It receives the original working directory and can, e.g., move files there from the sandbox.

Decorators:

• @contextlib.contextmanager

runs func in a temporary ("sandbox") directory.

func is called with args and kwargs. setUp and tearDown are two functions also called with args and kwargs; in addition, they are passed the path of the tempdir (setUp) or the path of the original directory (teardown) in the first argument.

setUp is called after the directory has been created, but the process is still in the current WD.

tearDown is called before the temp dir is deleted and in this directory. Its return value is the return value of runInSandbox, which is the preferred way of getting data out of the sandbox.

If any of the handlers raise exceptions, the following handlers will not be called. The sandbox will be torn down, though.

This is only present for legacy code. Use the sandbox context manager now.

imports a module from the module path.

Use this to programmatically import "normal" modules, e.g., dc-internal ones. It uses python's standard import mechanism and returns the module object.

We're using exec and python's normal import, so the semantics should be identical to saying import modName except that the caller's namespace is not changed.

The function returns the imported module.

imports fqName and returns the module with a module description.

The module description is what what find_module returns; you may need this for reloading and similar.

Do not use this function to import DC-internal modules; this may mess up singletons since you could bypass python's mechanisms to prevent multiple imports of the same module.

fqName is a fully qualified path to the module without the .py, unless relativeTo is given, in which case it is interpreted as a relative path. This for letting modules in resdir/res import each other by saying:

       mod, _ = api.loadPythonModule("foo", relativeTo=__file__)

The python path is temporarily amended with the path part of the source module.

If the module is in /var/gavo/inputs/foo/bar/mod.py, Python will know the module as foo_bar_mod (the last two path components are always added). This is to keep Python from using the module when someone writes import mod.

Decorators:

• @document

gets a name from an internal module.

relativeName is the python module path (not including "gavo."), objectName the name of something within the module.

This is used for "manual" registries (grammars, cores,...).

a trivial memoizing decorator.

Use this for plain functions; see memoizedMethod for instance methods. No cache expiry, no non-hashable arguments, nothing.

yields pairs of consecutive items from sequence.

If the last item cannot be paired, it is dropped.

>>> list(iterConsecutivePairs(range(6)))
[(0, 1), (2, 3), (4, 5)]
>>> list(iterConsecutivePairs(range(5)))
[(0, 1), (2, 3)]

yields (left, right) pairs for a sequence of separators.

>>> list(iterRanges(range(6)))
[(0, 1), (1, 2), (2, 3), (3, 4), (4, 5)]

returns a key of dict matching key case-insensitively.

This is sometimes useful with protocols that stupidly define keys as case-insensitive.

If no matching key exists, a KeyError is raised.

memoizes the result of generatingFunction on onObject.

This is for caching things that adapt to onObjects; see procdefs and rowmakers for examples why this is useful.

clears things memoizeOn-ed on ob or @utils.memoize-ed.

This is sometimes necessary to let the garbage collector free ob, e.g., when closures have been memoized.

returns the first local variable called varName in the frame stack above my caller.

This is obviously abominable. This is only used within the DC code where the author deemed the specification ugly. Ah. Almost.

prints a compact list of frames.

This is an aid for printf debugging.

__warningregistry__

Value:

{('The compiler package is deprecated and removed in Python 3.x.', <type 'exceptions.DeprecationWarning'>, 14): True}