Package: asset
Loads resources and symbols from a python package, whether installed
as a directory, an egg, or in source form. Also provides some other
package-related helper methods, includingasset.version(),asset.caller(), andasset.chunks().TL;DRInstall:$pipinstallassetLoad symbols (e.g. functions, classes, or variables) from a package by
name:importasset# load the 'mypackage.foo.myfunc' function and call it with some parameterretval=asset.symbol('mypackage.foo.myfunc')(param='value')Load data files from a package:# load the file 'mypackage/templates/data.txt' into stringdata=asset.load('mypackage:templates/data.txt').read()# or as a file-like streamstream=asset.load('mypackage:templates/data.txt').stream()data=stream.read()Multiple files can be operated on at once by usingglobrestyle wildcards:# concatenate all 'css' files into one string:css=asset.load('mypackage:static/style/**.css').read()# load all '.txt' files, XML-escaping the data and wrapping# each file in an <node name="...">...</node> element.importxml.etree.ElementTreeasETdata=ET.Element('nodes')foriteminasset.load('asset:**.txt'):cur=ET.SubElement(data,'node',name=item.name)cur.text=item.read()data=ET.tostring(data)Query the installed version of a package:asset.version('asset')# ==> '0.0.5'asset.version('python')# ==> '2.7'asset.version('no-such-package')# ==> NoneFind out what package is calling the current function:# assuming the call stack is:#   in package "zig" a function "x", which calls#   in package "bar" a function "y", which calls#   in package "foo" a function "callfoo" defined as:defcallfoo():asset.caller()# ==> 'bar'asset.caller(ignore='bar')# ==> 'zig'asset.caller(ignore=['bar','zig'])# ==> NoneCall all the plugins for a given group:forplugininasset.plugins('mypackage.plugins'):plugin.handle()Filter an object through all the plugins for a given group (if there
are no plugins, this will simply returnthing):result=asset.plugins('mypackage.plugins').filter(thing)Load all registered plugins, select the ones namedfooand invoke
them (this will fail if there is nofooplugin):result=asset.plugins('mypackage.plugins').select('foo').handle(thing)Chunk a file (or any file-like object) into 1 KiB chunks:withopen('/var/binary/data','rb')asfp:forchunkinasset.chunks(fp,1024):# ... do something with `chunk` ...Chunk an Asset stream (here using the.chunksalias method):forchunkinasset.load('mypackage:data/**.bin').chunks():# ... using the default chunk size (usually 8 KiB) ...TestingIn order to run the unit tests correctly, thepxmlpackage needs to
be installed as a zipped package (i.e. an “egg”) and theglobrepackage needs to be installed unzipped. To accomplish that, do:$easy_install--zip-okpxml$easy_install--always-unzipglobreThe reason is that the unit tests confirm thatassetcan load assets
from both zipped and unzipped packages, and can also identify in which
mode it is operating.DetailsTODO: add detailed docs…Asset.filename:If the asset represents a file on the filesystem, is the absolute
path to the specified file. Otherwise isNone.AssetGroupStream.readline():Returns the next line from the aggregate asset group stream, as if
the assets had been concatenate into a single asset.IMPORTANT: if an asset ends with content that is not terminated
by an EOL token, it is returned as-is, i.e. it does NOT append the
first line from the next asset.Note: becauseasset.load()does lazy-loading, it only throws aNoSuchAssetexception when you actually attempt to use the
AssetGroup! If you need an immediate error, use thepeek()method.
Note that it returns itself, so you can do something like:importassetdefmy_function_that_returns_an_iterable():returnasset.load(my_spec).peek()# this returns exactly the same thing as the following:##   return asset.load(my_spec)## but throws an exception early if there are no matching assets.