Home       Trees       Index       Help   

Aquarium

Package aquarium :: Package util :: Module InternalLibrary
[show private | hide private]
[frames | no frames]

Module aquarium.util.InternalLibrary

This is the "standard library" for Aquarium's structure.

Classes
InternalLibrary This is the "standard library" for Aquarium's structure.

Exceptions
FormValueError Subclass ValueError for form errors that shouldn't occur.
Forward Raise an instance of this class to make Aquarium do a forward.

Function Summary
  cacheByArgs(f, *args)
Cache the results of f.
  clearGetTextTranslations()
Clear gettext of stale translations.
  clearModules()
Clear sys.modules of specific types of modules if one is stale.
  getExceptionStr(etype, value, tb, *args, **kargs)
This is a convenience method for traceback.print_exception.
  isModified(lastUpdate, currentValue)
Is math.floor(lastUpdate) < math.floor(currentValue)?
  passStringIO(toArg, f, *args, **kargs)
Call f with a StringIO instead of an output file.
  validModuleName(name)
Return true if the given module name is valid.

Function Details

cacheByArgs(f, *args)

Cache the results of f. Vary by args.

The cache will be stored as an attribute of f named _cacheByArgs.

Note that everything in args must be hashable (this implies non-modifiable) because args is used as a dictionary key. For this same reason, I can't support **kargs (which would probably be pretty slow anyway).

Since the cache is attached to the function, it lives as long as the function does. If you need to throw the cache away on every request, use a new lambda for every request.

Use this function very carefully. Make sure you're not over-zealous in your cacheing; some things should not be cached. Also, make sure your cache doesn't just grow infinitely; you should test to make sure you don't create a memory leak. When you do test, remember to turn sessions off, or else you'll mistake the creation of a lot of sessions for a memory leak.

clearGetTextTranslations()

Clear gettext of stale translations.

Because translation instances can create a chain of interrelated fallbacks, if even one of them is stale, I clear them all.

This setting is controlled by properties.CLEAR_GETTEXT. However, if that is undefined (which is likely since it's only mentioned here), I will use the value:

properties.CLEAR_MODULES and properties.USE_GETTEXT

clearModules()

Clear sys.modules of specific types of modules if one is stale.

See properties.CLEAR_MODULES.

I took this method out of the InternalLibrary class so that you can call it really early, even before you create a Context to pass to InternalLibrary.

This function also calls clearGetTextTranslations.

History

The problem that this method solves is simple: if I change a file, I don't want to have to restart the server. It's a simple problem, but it's tough to implement right. To prevent repeating mistakes, here's what has failed in the past:

  • Remove all modules from sys.modules on every page load.
    • Some modules have state.
  • Delete only those modules that don't have state.
    • There's no convenient way to know which ones have state.
  • Use module attributes.
    • It's not convenient.
  • Delete only those modules that have grown stale.
    • If a parent class gets reloaded, child classes in other modules will need to get reloaded, but we don't know which modules those classes are in.
  • Look through all the modules for module references to the modules that'll get deleted and delete those too.
    • Its very common to only import the class, not the whole module. Hence, we still don't know which modules have child classes that need to get reloaded.
  • Just clear out sys.modules of all modules of certain types on every page load.
    • Even a moderate amount of kiddie clicking will result in exceptions. I think the browsers hide the problem, but you'll see the exceptions in the logs.
  • Clear out sys.modules of all modules of certain types on every page load, but only if at least one of the modules is stale.
    • This is good because it handles the kiddie clicking case, and it also handles the super class case.
  • We need to handle stale templates too. aquariumFactory use to do this, but it suffered from the same super class problem. Hence, if a .tmpl has been updated, its corresponding .py must be deleted. The other .py files don't need to be deleted. However, all the sys.modules need to be cleared, just in case some class was using a superclass from that .py.

getExceptionStr(etype=None, value=None, tb=None, *args, **kargs)

This is a convenience method for traceback.print_exception.

etype, value, tb
If you specify these, I'll call traceback.print_exception. Otherwise, I'll call traceback.print_exc.
args
These are additional arguments to print_exc or print_exception.

Instead of accepting an output file, I'll use a StringIO and then return the results as a string. That's the one bit of convenience I add.

isModified(lastUpdate, currentValue)

Is math.floor(lastUpdate) < math.floor(currentValue)?

lastUpdate
This is either a timestamp or a stat[ST_MTIME].
currentValue
This is a stat[ST_MTIME].

math.floor is used because the resolution of time.time() is higher than that of stat[ST_MTIME] on some operating systems / filesystems.

passStringIO(toArg, f, *args, **kargs)

Call f with a StringIO instead of an output file.

toArg
This is the name of one of f's parameters. Create a new StringIO object and pass it in for this parameter.
f
This is some function that takes an output file.
args, kargs
These will also be passed to f.

When f completes, serialize the StringIO to a string, and return that.

This function is really useful when working with traceback.print_exception.

validModuleName(name)

Return true if the given module name is valid.

This is valid: foo.bar These are not: .foo.bar, foo..bar, foo/bar, etc.

Please note that externally, screens use "/"'s, but this function expects those to have been changed to "."'s.


   Home       Trees       Index       Help   

Aquarium

Generated by Epydoc 2.1 on Mon Jan 1 16:34:19 2007 http://epydoc.sf.net