Import upstream version 0.6.13+git20191124.1.6922cf1
Kali Janitor
1 year, 6 months ago
| 0 | Metadata-Version: 1.1 | |
| 0 | Metadata-Version: 2.1 | |
| 1 | 1 | Name: asset |
| 2 | 2 | Version: 0.6.13 |
| 3 | 3 | Summary: A package resource and symbol loading helper library. |
| 5 | 5 | Author: metagriffin |
| 6 | 6 | Author-email: [email protected] |
| 7 | 7 | License: GPLv3+ |
| 8 | Description: ================================ | |
| 9 | Generalized Package Asset Loader | |
| 10 | ================================ | |
| 11 | ||
| 12 | Loads resources and symbols from a python package, whether installed | |
| 13 | as a directory, an egg, or in source form. Also provides some other | |
| 14 | package-related helper methods, including ``asset.version()``, | |
| 15 | ``asset.caller()``, and ``asset.chunks()``. | |
| 16 | ||
| 17 | TL;DR | |
| 18 | ===== | |
| 19 | ||
| 20 | Install: | |
| 21 | ||
| 22 | .. code:: bash | |
| 23 | ||
| 24 | $ pip install asset | |
| 25 | ||
| 26 | Load symbols (e.g. functions, classes, or variables) from a package by | |
| 27 | name: | |
| 28 | ||
| 29 | .. code:: python | |
| 30 | ||
| 31 | import asset | |
| 32 | ||
| 33 | # load the 'mypackage.foo.myfunc' function and call it with some parameter | |
| 34 | retval = asset.symbol('mypackage.foo.myfunc')(param='value') | |
| 35 | ||
| 36 | Load data files from a package: | |
| 37 | ||
| 38 | .. code:: python | |
| 39 | ||
| 40 | # load the file 'mypackage/templates/data.txt' into string | |
| 41 | data = asset.load('mypackage:templates/data.txt').read() | |
| 42 | ||
| 43 | # or as a file-like stream | |
| 44 | stream = asset.load('mypackage:templates/data.txt').stream() | |
| 45 | data = stream.read() | |
| 46 | ||
| 47 | Multiple files can be operated on at once by using `globre | |
| 48 | <https://pypi.python.org/pypi/globre>`_ style wildcards: | |
| 49 | ||
| 50 | .. code:: python | |
| 51 | ||
| 52 | # concatenate all 'css' files into one string: | |
| 53 | css = asset.load('mypackage:static/style/**.css').read() | |
| 54 | ||
| 55 | # load all '.txt' files, XML-escaping the data and wrapping | |
| 56 | # each file in an <node name="...">...</node> element. | |
| 57 | import xml.etree.ElementTree as ET | |
| 58 | data = ET.Element('nodes') | |
| 59 | for item in asset.load('asset:**.txt'): | |
| 60 | cur = ET.SubElement(data, 'node', name=item.name) | |
| 61 | cur.text = item.read() | |
| 62 | data = ET.tostring(data) | |
| 63 | ||
| 64 | Query the installed version of a package: | |
| 65 | ||
| 66 | .. code:: python | |
| 67 | ||
| 68 | asset.version('asset') | |
| 69 | # ==> '0.0.5' | |
| 70 | ||
| 71 | asset.version('python') | |
| 72 | # ==> '2.7' | |
| 73 | ||
| 74 | asset.version('no-such-package') | |
| 75 | # ==> None | |
| 76 | ||
| 77 | Find out what package is calling the current function: | |
| 78 | ||
| 79 | .. code:: python | |
| 80 | ||
| 81 | # assuming the call stack is: | |
| 82 | # in package "zig" a function "x", which calls | |
| 83 | # in package "bar" a function "y", which calls | |
| 84 | # in package "foo" a function "callfoo" defined as: | |
| 85 | ||
| 86 | def callfoo(): | |
| 87 | ||
| 88 | asset.caller() | |
| 89 | # ==> 'bar' | |
| 90 | ||
| 91 | asset.caller(ignore='bar') | |
| 92 | # ==> 'zig' | |
| 93 | ||
| 94 | asset.caller(ignore=['bar', 'zig']) | |
| 95 | # ==> None | |
| 96 | ||
| 97 | Call all the plugins for a given group: | |
| 98 | ||
| 99 | .. code:: python | |
| 100 | ||
| 101 | for plugin in asset.plugins('mypackage.plugins'): | |
| 102 | plugin.handle() | |
| 103 | ||
| 104 | Filter an object through all the plugins for a given group (if there | |
| 105 | are no plugins, this will simply return `thing`): | |
| 106 | ||
| 107 | .. code:: python | |
| 108 | ||
| 109 | result = asset.plugins('mypackage.plugins').filter(thing) | |
| 110 | ||
| 111 | Load all registered plugins, select the ones named `foo` and invoke | |
| 112 | them (this will fail if there is no `foo` plugin): | |
| 113 | ||
| 114 | .. code:: python | |
| 115 | ||
| 116 | result = asset.plugins('mypackage.plugins').select('foo').handle(thing) | |
| 117 | ||
| 118 | Chunk a file (or any file-like object) into 1 KiB chunks: | |
| 119 | ||
| 120 | .. code:: python | |
| 121 | ||
| 122 | with open('/var/binary/data', 'rb') as fp: | |
| 123 | for chunk in asset.chunks(fp, 1024): | |
| 124 | # ... do something with `chunk` ... | |
| 125 | ||
| 126 | Chunk an Asset stream (here using the `.chunks` alias method): | |
| 127 | ||
| 128 | .. code:: python | |
| 129 | ||
| 130 | for chunk in asset.load('mypackage:data/**.bin').chunks(): | |
| 131 | # ... using the default chunk size (usually 8 KiB) ... | |
| 132 | ||
| 133 | ||
| 134 | Testing | |
| 135 | ======= | |
| 136 | ||
| 137 | In order to run the unit tests correctly, the `pxml` package needs to | |
| 138 | be installed as a zipped package (i.e. an "egg") and the `globre` | |
| 139 | package needs to be installed unzipped. To accomplish that, do: | |
| 140 | ||
| 141 | .. code:: bash | |
| 142 | ||
| 143 | $ easy_install --zip-ok pxml | |
| 144 | $ easy_install --always-unzip globre | |
| 145 | ||
| 146 | The reason is that the unit tests confirm that `asset` can load assets | |
| 147 | from both zipped and unzipped packages, and can also identify in which | |
| 148 | mode it is operating. | |
| 149 | ||
| 150 | ||
| 151 | Details | |
| 152 | ======= | |
| 153 | ||
| 154 | TODO: add detailed docs... | |
| 155 | ||
| 156 | * ``Asset.filename``: | |
| 157 | ||
| 158 | If the asset represents a file on the filesystem, is the absolute | |
| 159 | path to the specified file. Otherwise is ``None``. | |
| 160 | ||
| 161 | * ``AssetGroupStream.readline()``: | |
| 162 | ||
| 163 | Returns the next line from the aggregate asset group stream, as if | |
| 164 | the assets had been concatenate into a single asset. | |
| 165 | ||
| 166 | **IMPORTANT**: if an asset ends with content that is not terminated | |
| 167 | by an EOL token, it is returned as-is, i.e. it does NOT append the | |
| 168 | first line from the next asset. | |
| 169 | ||
| 170 | Note: because ``asset.load()`` does lazy-loading, it only throws a | |
| 171 | `NoSuchAsset` exception when you actually attempt to use the | |
| 172 | AssetGroup! If you need an immediate error, use the `peek()` method. | |
| 173 | Note that it returns itself, so you can do something like: | |
| 174 | ||
| 175 | .. code:: python | |
| 176 | ||
| 177 | import asset | |
| 178 | ||
| 179 | def my_function_that_returns_an_iterable(): | |
| 180 | ||
| 181 | return asset.load(my_spec).peek() | |
| 182 | ||
| 183 | # this returns exactly the same thing as the following: | |
| 184 | # | |
| 185 | # return asset.load(my_spec) | |
| 186 | # | |
| 187 | # but throws an exception early if there are no matching assets. | |
| 188 | ||
| 189 | 8 | Keywords: python package pkg_resources asset resolve lookup loader |
| 190 | 9 | Platform: any |
| 191 | 10 | Classifier: Development Status :: 5 - Production/Stable |
| 194 | 13 | Classifier: Operating System :: OS Independent |
| 195 | 14 | Classifier: Natural Language :: English |
| 196 | 15 | Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+) |
| 16 | License-File: LICENSE.txt | |
| 17 | ||
| 18 | ================================ | |
| 19 | Generalized Package Asset Loader | |
| 20 | ================================ | |
| 21 | ||
| 22 | Loads resources and symbols from a python package, whether installed | |
| 23 | as a directory, an egg, or in source form. Also provides some other | |
| 24 | package-related helper methods, including ``asset.version()``, | |
| 25 | ``asset.caller()``, and ``asset.chunks()``. | |
| 26 | ||
| 27 | TL;DR | |
| 28 | ===== | |
| 29 | ||
| 30 | Install: | |
| 31 | ||
| 32 | .. code:: bash | |
| 33 | ||
| 34 | $ pip install asset | |
| 35 | ||
| 36 | Load symbols (e.g. functions, classes, or variables) from a package by | |
| 37 | name: | |
| 38 | ||
| 39 | .. code:: python | |
| 40 | ||
| 41 | import asset | |
| 42 | ||
| 43 | # load the 'mypackage.foo.myfunc' function and call it with some parameter | |
| 44 | retval = asset.symbol('mypackage.foo.myfunc')(param='value') | |
| 45 | ||
| 46 | Load data files from a package: | |
| 47 | ||
| 48 | .. code:: python | |
| 49 | ||
| 50 | # load the file 'mypackage/templates/data.txt' into string | |
| 51 | data = asset.load('mypackage:templates/data.txt').read() | |
| 52 | ||
| 53 | # or as a file-like stream | |
| 54 | stream = asset.load('mypackage:templates/data.txt').stream() | |
| 55 | data = stream.read() | |
| 56 | ||
| 57 | Multiple files can be operated on at once by using `globre | |
| 58 | <https://pypi.python.org/pypi/globre>`_ style wildcards: | |
| 59 | ||
| 60 | .. code:: python | |
| 61 | ||
| 62 | # concatenate all 'css' files into one string: | |
| 63 | css = asset.load('mypackage:static/style/**.css').read() | |
| 64 | ||
| 65 | # load all '.txt' files, XML-escaping the data and wrapping | |
| 66 | # each file in an <node name="...">...</node> element. | |
| 67 | import xml.etree.ElementTree as ET | |
| 68 | data = ET.Element('nodes') | |
| 69 | for item in asset.load('asset:**.txt'): | |
| 70 | cur = ET.SubElement(data, 'node', name=item.name) | |
| 71 | cur.text = item.read() | |
| 72 | data = ET.tostring(data) | |
| 73 | ||
| 74 | Query the installed version of a package: | |
| 75 | ||
| 76 | .. code:: python | |
| 77 | ||
| 78 | asset.version('asset') | |
| 79 | # ==> '0.0.5' | |
| 80 | ||
| 81 | asset.version('python') | |
| 82 | # ==> '2.7' | |
| 83 | ||
| 84 | asset.version('no-such-package') | |
| 85 | # ==> None | |
| 86 | ||
| 87 | Find out what package is calling the current function: | |
| 88 | ||
| 89 | .. code:: python | |
| 90 | ||
| 91 | # assuming the call stack is: | |
| 92 | # in package "zig" a function "x", which calls | |
| 93 | # in package "bar" a function "y", which calls | |
| 94 | # in package "foo" a function "callfoo" defined as: | |
| 95 | ||
| 96 | def callfoo(): | |
| 97 | ||
| 98 | asset.caller() | |
| 99 | # ==> 'bar' | |
| 100 | ||
| 101 | asset.caller(ignore='bar') | |
| 102 | # ==> 'zig' | |
| 103 | ||
| 104 | asset.caller(ignore=['bar', 'zig']) | |
| 105 | # ==> None | |
| 106 | ||
| 107 | Call all the plugins for a given group: | |
| 108 | ||
| 109 | .. code:: python | |
| 110 | ||
| 111 | for plugin in asset.plugins('mypackage.plugins'): | |
| 112 | plugin.handle() | |
| 113 | ||
| 114 | Filter an object through all the plugins for a given group (if there | |
| 115 | are no plugins, this will simply return `thing`): | |
| 116 | ||
| 117 | .. code:: python | |
| 118 | ||
| 119 | result = asset.plugins('mypackage.plugins').filter(thing) | |
| 120 | ||
| 121 | Load all registered plugins, select the ones named `foo` and invoke | |
| 122 | them (this will fail if there is no `foo` plugin): | |
| 123 | ||
| 124 | .. code:: python | |
| 125 | ||
| 126 | result = asset.plugins('mypackage.plugins').select('foo').handle(thing) | |
| 127 | ||
| 128 | Chunk a file (or any file-like object) into 1 KiB chunks: | |
| 129 | ||
| 130 | .. code:: python | |
| 131 | ||
| 132 | with open('/var/binary/data', 'rb') as fp: | |
| 133 | for chunk in asset.chunks(fp, 1024): | |
| 134 | # ... do something with `chunk` ... | |
| 135 | ||
| 136 | Chunk an Asset stream (here using the `.chunks` alias method): | |
| 137 | ||
| 138 | .. code:: python | |
| 139 | ||
| 140 | for chunk in asset.load('mypackage:data/**.bin').chunks(): | |
| 141 | # ... using the default chunk size (usually 8 KiB) ... | |
| 142 | ||
| 143 | ||
| 144 | Testing | |
| 145 | ======= | |
| 146 | ||
| 147 | In order to run the unit tests correctly, the `pxml` package needs to | |
| 148 | be installed as a zipped package (i.e. an "egg") and the `globre` | |
| 149 | package needs to be installed unzipped. To accomplish that, do: | |
| 150 | ||
| 151 | .. code:: bash | |
| 152 | ||
| 153 | $ easy_install --zip-ok pxml | |
| 154 | $ easy_install --always-unzip globre | |
| 155 | ||
| 156 | The reason is that the unit tests confirm that `asset` can load assets | |
| 157 | from both zipped and unzipped packages, and can also identify in which | |
| 158 | mode it is operating. | |
| 159 | ||
| 160 | ||
| 161 | Details | |
| 162 | ======= | |
| 163 | ||
| 164 | TODO: add detailed docs... | |
| 165 | ||
| 166 | * ``Asset.filename``: | |
| 167 | ||
| 168 | If the asset represents a file on the filesystem, is the absolute | |
| 169 | path to the specified file. Otherwise is ``None``. | |
| 170 | ||
| 171 | * ``AssetGroupStream.readline()``: | |
| 172 | ||
| 173 | Returns the next line from the aggregate asset group stream, as if | |
| 174 | the assets had been concatenate into a single asset. | |
| 175 | ||
| 176 | **IMPORTANT**: if an asset ends with content that is not terminated | |
| 177 | by an EOL token, it is returned as-is, i.e. it does NOT append the | |
| 178 | first line from the next asset. | |
| 179 | ||
| 180 | Note: because ``asset.load()`` does lazy-loading, it only throws a | |
| 181 | `NoSuchAsset` exception when you actually attempt to use the | |
| 182 | AssetGroup! If you need an immediate error, use the `peek()` method. | |
| 183 | Note that it returns itself, so you can do something like: | |
| 184 | ||
| 185 | .. code:: python | |
| 186 | ||
| 187 | import asset | |
| 188 | ||
| 189 | def my_function_that_returns_an_iterable(): | |
| 190 | ||
| 191 | return asset.load(my_spec).peek() | |
| 192 | ||
| 193 | # this returns exactly the same thing as the following: | |
| 194 | # | |
| 195 | # return asset.load(my_spec) | |
| 196 | # | |
| 197 | # but throws an exception early if there are no matching assets. | |
| 0 | * make this work:: | |
| 1 | ||
| 2 | from nitro.utils import csviter | |
| 3 | import asset | |
| 4 | for record in csviter(asset.load('{ASSETSPEC}')): | |
| 5 | ... | |
| 6 | ||
| 7 | currently, it results in:: | |
| 8 | ||
| 9 | TypeError: expected string or Unicode object, Asset found | |
| 10 | ||
| 11 | 0 | * make it easy to create a plugin helper, eg instead of: |
| 12 | 1 | |
| 13 | 2 | @asset.plugin('jstc.precompilers.plugins', 'text/x-easytpl') |
| 0 | Metadata-Version: 1.1 | |
| 0 | Metadata-Version: 2.1 | |
| 1 | 1 | Name: asset |
| 2 | 2 | Version: 0.6.13 |
| 3 | 3 | Summary: A package resource and symbol loading helper library. |
| 5 | 5 | Author: metagriffin |
| 6 | 6 | Author-email: [email protected] |
| 7 | 7 | License: GPLv3+ |
| 8 | Description: ================================ | |
| 9 | Generalized Package Asset Loader | |
| 10 | ================================ | |
| 11 | ||
| 12 | Loads resources and symbols from a python package, whether installed | |
| 13 | as a directory, an egg, or in source form. Also provides some other | |
| 14 | package-related helper methods, including ``asset.version()``, | |
| 15 | ``asset.caller()``, and ``asset.chunks()``. | |
| 16 | ||
| 17 | TL;DR | |
| 18 | ===== | |
| 19 | ||
| 20 | Install: | |
| 21 | ||
| 22 | .. code:: bash | |
| 23 | ||
| 24 | $ pip install asset | |
| 25 | ||
| 26 | Load symbols (e.g. functions, classes, or variables) from a package by | |
| 27 | name: | |
| 28 | ||
| 29 | .. code:: python | |
| 30 | ||
| 31 | import asset | |
| 32 | ||
| 33 | # load the 'mypackage.foo.myfunc' function and call it with some parameter | |
| 34 | retval = asset.symbol('mypackage.foo.myfunc')(param='value') | |
| 35 | ||
| 36 | Load data files from a package: | |
| 37 | ||
| 38 | .. code:: python | |
| 39 | ||
| 40 | # load the file 'mypackage/templates/data.txt' into string | |
| 41 | data = asset.load('mypackage:templates/data.txt').read() | |
| 42 | ||
| 43 | # or as a file-like stream | |
| 44 | stream = asset.load('mypackage:templates/data.txt').stream() | |
| 45 | data = stream.read() | |
| 46 | ||
| 47 | Multiple files can be operated on at once by using `globre | |
| 48 | <https://pypi.python.org/pypi/globre>`_ style wildcards: | |
| 49 | ||
| 50 | .. code:: python | |
| 51 | ||
| 52 | # concatenate all 'css' files into one string: | |
| 53 | css = asset.load('mypackage:static/style/**.css').read() | |
| 54 | ||
| 55 | # load all '.txt' files, XML-escaping the data and wrapping | |
| 56 | # each file in an <node name="...">...</node> element. | |
| 57 | import xml.etree.ElementTree as ET | |
| 58 | data = ET.Element('nodes') | |
| 59 | for item in asset.load('asset:**.txt'): | |
| 60 | cur = ET.SubElement(data, 'node', name=item.name) | |
| 61 | cur.text = item.read() | |
| 62 | data = ET.tostring(data) | |
| 63 | ||
| 64 | Query the installed version of a package: | |
| 65 | ||
| 66 | .. code:: python | |
| 67 | ||
| 68 | asset.version('asset') | |
| 69 | # ==> '0.0.5' | |
| 70 | ||
| 71 | asset.version('python') | |
| 72 | # ==> '2.7' | |
| 73 | ||
| 74 | asset.version('no-such-package') | |
| 75 | # ==> None | |
| 76 | ||
| 77 | Find out what package is calling the current function: | |
| 78 | ||
| 79 | .. code:: python | |
| 80 | ||
| 81 | # assuming the call stack is: | |
| 82 | # in package "zig" a function "x", which calls | |
| 83 | # in package "bar" a function "y", which calls | |
| 84 | # in package "foo" a function "callfoo" defined as: | |
| 85 | ||
| 86 | def callfoo(): | |
| 87 | ||
| 88 | asset.caller() | |
| 89 | # ==> 'bar' | |
| 90 | ||
| 91 | asset.caller(ignore='bar') | |
| 92 | # ==> 'zig' | |
| 93 | ||
| 94 | asset.caller(ignore=['bar', 'zig']) | |
| 95 | # ==> None | |
| 96 | ||
| 97 | Call all the plugins for a given group: | |
| 98 | ||
| 99 | .. code:: python | |
| 100 | ||
| 101 | for plugin in asset.plugins('mypackage.plugins'): | |
| 102 | plugin.handle() | |
| 103 | ||
| 104 | Filter an object through all the plugins for a given group (if there | |
| 105 | are no plugins, this will simply return `thing`): | |
| 106 | ||
| 107 | .. code:: python | |
| 108 | ||
| 109 | result = asset.plugins('mypackage.plugins').filter(thing) | |
| 110 | ||
| 111 | Load all registered plugins, select the ones named `foo` and invoke | |
| 112 | them (this will fail if there is no `foo` plugin): | |
| 113 | ||
| 114 | .. code:: python | |
| 115 | ||
| 116 | result = asset.plugins('mypackage.plugins').select('foo').handle(thing) | |
| 117 | ||
| 118 | Chunk a file (or any file-like object) into 1 KiB chunks: | |
| 119 | ||
| 120 | .. code:: python | |
| 121 | ||
| 122 | with open('/var/binary/data', 'rb') as fp: | |
| 123 | for chunk in asset.chunks(fp, 1024): | |
| 124 | # ... do something with `chunk` ... | |
| 125 | ||
| 126 | Chunk an Asset stream (here using the `.chunks` alias method): | |
| 127 | ||
| 128 | .. code:: python | |
| 129 | ||
| 130 | for chunk in asset.load('mypackage:data/**.bin').chunks(): | |
| 131 | # ... using the default chunk size (usually 8 KiB) ... | |
| 132 | ||
| 133 | ||
| 134 | Testing | |
| 135 | ======= | |
| 136 | ||
| 137 | In order to run the unit tests correctly, the `pxml` package needs to | |
| 138 | be installed as a zipped package (i.e. an "egg") and the `globre` | |
| 139 | package needs to be installed unzipped. To accomplish that, do: | |
| 140 | ||
| 141 | .. code:: bash | |
| 142 | ||
| 143 | $ easy_install --zip-ok pxml | |
| 144 | $ easy_install --always-unzip globre | |
| 145 | ||
| 146 | The reason is that the unit tests confirm that `asset` can load assets | |
| 147 | from both zipped and unzipped packages, and can also identify in which | |
| 148 | mode it is operating. | |
| 149 | ||
| 150 | ||
| 151 | Details | |
| 152 | ======= | |
| 153 | ||
| 154 | TODO: add detailed docs... | |
| 155 | ||
| 156 | * ``Asset.filename``: | |
| 157 | ||
| 158 | If the asset represents a file on the filesystem, is the absolute | |
| 159 | path to the specified file. Otherwise is ``None``. | |
| 160 | ||
| 161 | * ``AssetGroupStream.readline()``: | |
| 162 | ||
| 163 | Returns the next line from the aggregate asset group stream, as if | |
| 164 | the assets had been concatenate into a single asset. | |
| 165 | ||
| 166 | **IMPORTANT**: if an asset ends with content that is not terminated | |
| 167 | by an EOL token, it is returned as-is, i.e. it does NOT append the | |
| 168 | first line from the next asset. | |
| 169 | ||
| 170 | Note: because ``asset.load()`` does lazy-loading, it only throws a | |
| 171 | `NoSuchAsset` exception when you actually attempt to use the | |
| 172 | AssetGroup! If you need an immediate error, use the `peek()` method. | |
| 173 | Note that it returns itself, so you can do something like: | |
| 174 | ||
| 175 | .. code:: python | |
| 176 | ||
| 177 | import asset | |
| 178 | ||
| 179 | def my_function_that_returns_an_iterable(): | |
| 180 | ||
| 181 | return asset.load(my_spec).peek() | |
| 182 | ||
| 183 | # this returns exactly the same thing as the following: | |
| 184 | # | |
| 185 | # return asset.load(my_spec) | |
| 186 | # | |
| 187 | # but throws an exception early if there are no matching assets. | |
| 188 | ||
| 189 | 8 | Keywords: python package pkg_resources asset resolve lookup loader |
| 190 | 9 | Platform: any |
| 191 | 10 | Classifier: Development Status :: 5 - Production/Stable |
| 194 | 13 | Classifier: Operating System :: OS Independent |
| 195 | 14 | Classifier: Natural Language :: English |
| 196 | 15 | Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+) |
| 16 | License-File: LICENSE.txt | |
| 17 | ||
| 18 | ================================ | |
| 19 | Generalized Package Asset Loader | |
| 20 | ================================ | |
| 21 | ||
| 22 | Loads resources and symbols from a python package, whether installed | |
| 23 | as a directory, an egg, or in source form. Also provides some other | |
| 24 | package-related helper methods, including ``asset.version()``, | |
| 25 | ``asset.caller()``, and ``asset.chunks()``. | |
| 26 | ||
| 27 | TL;DR | |
| 28 | ===== | |
| 29 | ||
| 30 | Install: | |
| 31 | ||
| 32 | .. code:: bash | |
| 33 | ||
| 34 | $ pip install asset | |
| 35 | ||
| 36 | Load symbols (e.g. functions, classes, or variables) from a package by | |
| 37 | name: | |
| 38 | ||
| 39 | .. code:: python | |
| 40 | ||
| 41 | import asset | |
| 42 | ||
| 43 | # load the 'mypackage.foo.myfunc' function and call it with some parameter | |
| 44 | retval = asset.symbol('mypackage.foo.myfunc')(param='value') | |
| 45 | ||
| 46 | Load data files from a package: | |
| 47 | ||
| 48 | .. code:: python | |
| 49 | ||
| 50 | # load the file 'mypackage/templates/data.txt' into string | |
| 51 | data = asset.load('mypackage:templates/data.txt').read() | |
| 52 | ||
| 53 | # or as a file-like stream | |
| 54 | stream = asset.load('mypackage:templates/data.txt').stream() | |
| 55 | data = stream.read() | |
| 56 | ||
| 57 | Multiple files can be operated on at once by using `globre | |
| 58 | <https://pypi.python.org/pypi/globre>`_ style wildcards: | |
| 59 | ||
| 60 | .. code:: python | |
| 61 | ||
| 62 | # concatenate all 'css' files into one string: | |
| 63 | css = asset.load('mypackage:static/style/**.css').read() | |
| 64 | ||
| 65 | # load all '.txt' files, XML-escaping the data and wrapping | |
| 66 | # each file in an <node name="...">...</node> element. | |
| 67 | import xml.etree.ElementTree as ET | |
| 68 | data = ET.Element('nodes') | |
| 69 | for item in asset.load('asset:**.txt'): | |
| 70 | cur = ET.SubElement(data, 'node', name=item.name) | |
| 71 | cur.text = item.read() | |
| 72 | data = ET.tostring(data) | |
| 73 | ||
| 74 | Query the installed version of a package: | |
| 75 | ||
| 76 | .. code:: python | |
| 77 | ||
| 78 | asset.version('asset') | |
| 79 | # ==> '0.0.5' | |
| 80 | ||
| 81 | asset.version('python') | |
| 82 | # ==> '2.7' | |
| 83 | ||
| 84 | asset.version('no-such-package') | |
| 85 | # ==> None | |
| 86 | ||
| 87 | Find out what package is calling the current function: | |
| 88 | ||
| 89 | .. code:: python | |
| 90 | ||
| 91 | # assuming the call stack is: | |
| 92 | # in package "zig" a function "x", which calls | |
| 93 | # in package "bar" a function "y", which calls | |
| 94 | # in package "foo" a function "callfoo" defined as: | |
| 95 | ||
| 96 | def callfoo(): | |
| 97 | ||
| 98 | asset.caller() | |
| 99 | # ==> 'bar' | |
| 100 | ||
| 101 | asset.caller(ignore='bar') | |
| 102 | # ==> 'zig' | |
| 103 | ||
| 104 | asset.caller(ignore=['bar', 'zig']) | |
| 105 | # ==> None | |
| 106 | ||
| 107 | Call all the plugins for a given group: | |
| 108 | ||
| 109 | .. code:: python | |
| 110 | ||
| 111 | for plugin in asset.plugins('mypackage.plugins'): | |
| 112 | plugin.handle() | |
| 113 | ||
| 114 | Filter an object through all the plugins for a given group (if there | |
| 115 | are no plugins, this will simply return `thing`): | |
| 116 | ||
| 117 | .. code:: python | |
| 118 | ||
| 119 | result = asset.plugins('mypackage.plugins').filter(thing) | |
| 120 | ||
| 121 | Load all registered plugins, select the ones named `foo` and invoke | |
| 122 | them (this will fail if there is no `foo` plugin): | |
| 123 | ||
| 124 | .. code:: python | |
| 125 | ||
| 126 | result = asset.plugins('mypackage.plugins').select('foo').handle(thing) | |
| 127 | ||
| 128 | Chunk a file (or any file-like object) into 1 KiB chunks: | |
| 129 | ||
| 130 | .. code:: python | |
| 131 | ||
| 132 | with open('/var/binary/data', 'rb') as fp: | |
| 133 | for chunk in asset.chunks(fp, 1024): | |
| 134 | # ... do something with `chunk` ... | |
| 135 | ||
| 136 | Chunk an Asset stream (here using the `.chunks` alias method): | |
| 137 | ||
| 138 | .. code:: python | |
| 139 | ||
| 140 | for chunk in asset.load('mypackage:data/**.bin').chunks(): | |
| 141 | # ... using the default chunk size (usually 8 KiB) ... | |
| 142 | ||
| 143 | ||
| 144 | Testing | |
| 145 | ======= | |
| 146 | ||
| 147 | In order to run the unit tests correctly, the `pxml` package needs to | |
| 148 | be installed as a zipped package (i.e. an "egg") and the `globre` | |
| 149 | package needs to be installed unzipped. To accomplish that, do: | |
| 150 | ||
| 151 | .. code:: bash | |
| 152 | ||
| 153 | $ easy_install --zip-ok pxml | |
| 154 | $ easy_install --always-unzip globre | |
| 155 | ||
| 156 | The reason is that the unit tests confirm that `asset` can load assets | |
| 157 | from both zipped and unzipped packages, and can also identify in which | |
| 158 | mode it is operating. | |
| 159 | ||
| 160 | ||
| 161 | Details | |
| 162 | ======= | |
| 163 | ||
| 164 | TODO: add detailed docs... | |
| 165 | ||
| 166 | * ``Asset.filename``: | |
| 167 | ||
| 168 | If the asset represents a file on the filesystem, is the absolute | |
| 169 | path to the specified file. Otherwise is ``None``. | |
| 170 | ||
| 171 | * ``AssetGroupStream.readline()``: | |
| 172 | ||
| 173 | Returns the next line from the aggregate asset group stream, as if | |
| 174 | the assets had been concatenate into a single asset. | |
| 175 | ||
| 176 | **IMPORTANT**: if an asset ends with content that is not terminated | |
| 177 | by an EOL token, it is returned as-is, i.e. it does NOT append the | |
| 178 | first line from the next asset. | |
| 179 | ||
| 180 | Note: because ``asset.load()`` does lazy-loading, it only throws a | |
| 181 | `NoSuchAsset` exception when you actually attempt to use the | |
| 182 | AssetGroup! If you need an immediate error, use the `peek()` method. | |
| 183 | Note that it returns itself, so you can do something like: | |
| 184 | ||
| 185 | .. code:: python | |
| 186 | ||
| 187 | import asset | |
| 188 | ||
| 189 | def my_function_that_returns_an_iterable(): | |
| 190 | ||
| 191 | return asset.load(my_spec).peek() | |
| 192 | ||
| 193 | # this returns exactly the same thing as the following: | |
| 194 | # | |
| 195 | # return asset.load(my_spec) | |
| 196 | # | |
| 197 | # but throws an exception early if there are no matching assets. | |