New upstream version 0.6.13
Sophie Brun
3 years ago
0 | ========= | |
1 | ChangeLog | |
2 | ========= | |
3 | ||
4 | ||
5 | v0.6.13 | |
6 | ======= | |
7 | ||
8 | * Added `exists()` top-level module helper function | |
9 | ||
10 | ||
11 | v0.6.12 | |
12 | ======= | |
13 | ||
14 | * Added `chunks()` helper function and Asset methods for binary- or | |
15 | line-oriented stream chunking | |
16 | ||
17 | ||
18 | v0.6.11 | |
19 | ======= | |
20 | ||
21 | * Added `Asset.count()` helper function (alias to ``len(Asset)``) | |
22 | * Added `Asset.exists()` helper function (non-exception-based version of | |
23 | ``Asset.peek()``) | |
24 | ||
25 | ||
26 | v0.6.10 | |
27 | ======= | |
28 | ||
29 | * Added plugin loading error logging | |
30 | * Fixed symbol loading bug when using ':' separator | |
31 | ||
32 | ||
33 | v0.6.9 | |
34 | ====== | |
35 | ||
36 | * Added `PluginSet.select(name)` plugin selection method. | |
37 | ||
38 | ||
39 | v0.6.8 | |
40 | ====== | |
41 | ||
42 | * Enhanced return value from `asset.plugins` to be a first-class | |
43 | object (`PluginSet`) that has aggregate plugin operation methods | |
44 | `PluginSet.handle` and `PluginSet.filter`. | |
45 | ||
46 | ||
47 | v0.6.7 | |
48 | ====== | |
49 | ||
50 | * Added initial implementation of `asset.plugin` helper decorator | |
51 | ||
52 | ||
53 | v0.6.6 | |
54 | ====== | |
55 | ||
56 | * Corrected regex negative handling | |
57 | ||
58 | ||
59 | v0.6.5 | |
60 | ====== | |
61 | ||
62 | * Updated `asset.plugins` to support loading of unregistered plugins | |
63 | * Changed ``'!'`` `asset.plugins` prefix to ``'-'`` | |
64 | ||
65 | ||
66 | v0.6.4 | |
67 | ====== | |
68 | ||
69 | * Added `asset.plugins` plugin loading mechanism that supports simple | |
70 | ordering and overriding of plugins | |
71 | ||
72 | ||
73 | v0.6.3 | |
74 | ====== | |
75 | ||
76 | * Added check for egg vs. not-egg in unit tests | |
77 | ||
78 | ||
79 | v0.6.2 | |
80 | ====== | |
81 | ||
82 | * Removed distribute dependency (thanks jlec) | |
83 | ||
84 | ||
85 | v0.6.1 | |
86 | ====== | |
87 | ||
88 | * Added Python 3 support | |
89 | ||
90 | ||
91 | v0.6 | |
92 | ==== | |
93 | ||
94 | * Added more standard file object compatibility (stream iteration, | |
95 | reading with size, and closing) | |
96 | ||
97 | ||
98 | v0.0.5 | |
99 | ====== | |
100 | ||
101 | * Promoted to "stable" development status | |
102 | * First tagged release | |
103 | * Added `asset.version()` helper function |
0 | GNU GENERAL PUBLIC LICENSE | |
1 | Version 3, 29 June 2007 | |
2 | ||
3 | Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/> | |
4 | Everyone is permitted to copy and distribute verbatim copies | |
5 | of this license document, but changing it is not allowed. | |
6 | ||
7 | Preamble | |
8 | ||
9 | The GNU General Public License is a free, copyleft license for | |
10 | software and other kinds of works. | |
11 | ||
12 | The licenses for most software and other practical works are designed | |
13 | to take away your freedom to share and change the works. By contrast, | |
14 | the GNU General Public License is intended to guarantee your freedom to | |
15 | share and change all versions of a program--to make sure it remains free | |
16 | software for all its users. We, the Free Software Foundation, use the | |
17 | GNU General Public License for most of our software; it applies also to | |
18 | any other work released this way by its authors. You can apply it to | |
19 | your programs, too. | |
20 | ||
21 | When we speak of free software, we are referring to freedom, not | |
22 | price. Our General Public Licenses are designed to make sure that you | |
23 | have the freedom to distribute copies of free software (and charge for | |
24 | them if you wish), that you receive source code or can get it if you | |
25 | want it, that you can change the software or use pieces of it in new | |
26 | free programs, and that you know you can do these things. | |
27 | ||
28 | To protect your rights, we need to prevent others from denying you | |
29 | these rights or asking you to surrender the rights. Therefore, you have | |
30 | certain responsibilities if you distribute copies of the software, or if | |
31 | you modify it: responsibilities to respect the freedom of others. | |
32 | ||
33 | For example, if you distribute copies of such a program, whether | |
34 | gratis or for a fee, you must pass on to the recipients the same | |
35 | freedoms that you received. You must make sure that they, too, receive | |
36 | or can get the source code. And you must show them these terms so they | |
37 | know their rights. | |
38 | ||
39 | Developers that use the GNU GPL protect your rights with two steps: | |
40 | (1) assert copyright on the software, and (2) offer you this License | |
41 | giving you legal permission to copy, distribute and/or modify it. | |
42 | ||
43 | For the developers' and authors' protection, the GPL clearly explains | |
44 | that there is no warranty for this free software. For both users' and | |
45 | authors' sake, the GPL requires that modified versions be marked as | |
46 | changed, so that their problems will not be attributed erroneously to | |
47 | authors of previous versions. | |
48 | ||
49 | Some devices are designed to deny users access to install or run | |
50 | modified versions of the software inside them, although the manufacturer | |
51 | can do so. This is fundamentally incompatible with the aim of | |
52 | protecting users' freedom to change the software. The systematic | |
53 | pattern of such abuse occurs in the area of products for individuals to | |
54 | use, which is precisely where it is most unacceptable. Therefore, we | |
55 | have designed this version of the GPL to prohibit the practice for those | |
56 | products. If such problems arise substantially in other domains, we | |
57 | stand ready to extend this provision to those domains in future versions | |
58 | of the GPL, as needed to protect the freedom of users. | |
59 | ||
60 | Finally, every program is threatened constantly by software patents. | |
61 | States should not allow patents to restrict development and use of | |
62 | software on general-purpose computers, but in those that do, we wish to | |
63 | avoid the special danger that patents applied to a free program could | |
64 | make it effectively proprietary. To prevent this, the GPL assures that | |
65 | patents cannot be used to render the program non-free. | |
66 | ||
67 | The precise terms and conditions for copying, distribution and | |
68 | modification follow. | |
69 | ||
70 | TERMS AND CONDITIONS | |
71 | ||
72 | 0. Definitions. | |
73 | ||
74 | "This License" refers to version 3 of the GNU General Public License. | |
75 | ||
76 | "Copyright" also means copyright-like laws that apply to other kinds of | |
77 | works, such as semiconductor masks. | |
78 | ||
79 | "The Program" refers to any copyrightable work licensed under this | |
80 | License. Each licensee is addressed as "you". "Licensees" and | |
81 | "recipients" may be individuals or organizations. | |
82 | ||
83 | To "modify" a work means to copy from or adapt all or part of the work | |
84 | in a fashion requiring copyright permission, other than the making of an | |
85 | exact copy. The resulting work is called a "modified version" of the | |
86 | earlier work or a work "based on" the earlier work. | |
87 | ||
88 | A "covered work" means either the unmodified Program or a work based | |
89 | on the Program. | |
90 | ||
91 | To "propagate" a work means to do anything with it that, without | |
92 | permission, would make you directly or secondarily liable for | |
93 | infringement under applicable copyright law, except executing it on a | |
94 | computer or modifying a private copy. Propagation includes copying, | |
95 | distribution (with or without modification), making available to the | |
96 | public, and in some countries other activities as well. | |
97 | ||
98 | To "convey" a work means any kind of propagation that enables other | |
99 | parties to make or receive copies. Mere interaction with a user through | |
100 | a computer network, with no transfer of a copy, is not conveying. | |
101 | ||
102 | An interactive user interface displays "Appropriate Legal Notices" | |
103 | to the extent that it includes a convenient and prominently visible | |
104 | feature that (1) displays an appropriate copyright notice, and (2) | |
105 | tells the user that there is no warranty for the work (except to the | |
106 | extent that warranties are provided), that licensees may convey the | |
107 | work under this License, and how to view a copy of this License. If | |
108 | the interface presents a list of user commands or options, such as a | |
109 | menu, a prominent item in the list meets this criterion. | |
110 | ||
111 | 1. Source Code. | |
112 | ||
113 | The "source code" for a work means the preferred form of the work | |
114 | for making modifications to it. "Object code" means any non-source | |
115 | form of a work. | |
116 | ||
117 | A "Standard Interface" means an interface that either is an official | |
118 | standard defined by a recognized standards body, or, in the case of | |
119 | interfaces specified for a particular programming language, one that | |
120 | is widely used among developers working in that language. | |
121 | ||
122 | The "System Libraries" of an executable work include anything, other | |
123 | than the work as a whole, that (a) is included in the normal form of | |
124 | packaging a Major Component, but which is not part of that Major | |
125 | Component, and (b) serves only to enable use of the work with that | |
126 | Major Component, or to implement a Standard Interface for which an | |
127 | implementation is available to the public in source code form. A | |
128 | "Major Component", in this context, means a major essential component | |
129 | (kernel, window system, and so on) of the specific operating system | |
130 | (if any) on which the executable work runs, or a compiler used to | |
131 | produce the work, or an object code interpreter used to run it. | |
132 | ||
133 | The "Corresponding Source" for a work in object code form means all | |
134 | the source code needed to generate, install, and (for an executable | |
135 | work) run the object code and to modify the work, including scripts to | |
136 | control those activities. However, it does not include the work's | |
137 | System Libraries, or general-purpose tools or generally available free | |
138 | programs which are used unmodified in performing those activities but | |
139 | which are not part of the work. For example, Corresponding Source | |
140 | includes interface definition files associated with source files for | |
141 | the work, and the source code for shared libraries and dynamically | |
142 | linked subprograms that the work is specifically designed to require, | |
143 | such as by intimate data communication or control flow between those | |
144 | subprograms and other parts of the work. | |
145 | ||
146 | The Corresponding Source need not include anything that users | |
147 | can regenerate automatically from other parts of the Corresponding | |
148 | Source. | |
149 | ||
150 | The Corresponding Source for a work in source code form is that | |
151 | same work. | |
152 | ||
153 | 2. Basic Permissions. | |
154 | ||
155 | All rights granted under this License are granted for the term of | |
156 | copyright on the Program, and are irrevocable provided the stated | |
157 | conditions are met. This License explicitly affirms your unlimited | |
158 | permission to run the unmodified Program. The output from running a | |
159 | covered work is covered by this License only if the output, given its | |
160 | content, constitutes a covered work. This License acknowledges your | |
161 | rights of fair use or other equivalent, as provided by copyright law. | |
162 | ||
163 | You may make, run and propagate covered works that you do not | |
164 | convey, without conditions so long as your license otherwise remains | |
165 | in force. You may convey covered works to others for the sole purpose | |
166 | of having them make modifications exclusively for you, or provide you | |
167 | with facilities for running those works, provided that you comply with | |
168 | the terms of this License in conveying all material for which you do | |
169 | not control copyright. Those thus making or running the covered works | |
170 | for you must do so exclusively on your behalf, under your direction | |
171 | and control, on terms that prohibit them from making any copies of | |
172 | your copyrighted material outside their relationship with you. | |
173 | ||
174 | Conveying under any other circumstances is permitted solely under | |
175 | the conditions stated below. Sublicensing is not allowed; section 10 | |
176 | makes it unnecessary. | |
177 | ||
178 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. | |
179 | ||
180 | No covered work shall be deemed part of an effective technological | |
181 | measure under any applicable law fulfilling obligations under article | |
182 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or | |
183 | similar laws prohibiting or restricting circumvention of such | |
184 | measures. | |
185 | ||
186 | When you convey a covered work, you waive any legal power to forbid | |
187 | circumvention of technological measures to the extent such circumvention | |
188 | is effected by exercising rights under this License with respect to | |
189 | the covered work, and you disclaim any intention to limit operation or | |
190 | modification of the work as a means of enforcing, against the work's | |
191 | users, your or third parties' legal rights to forbid circumvention of | |
192 | technological measures. | |
193 | ||
194 | 4. Conveying Verbatim Copies. | |
195 | ||
196 | You may convey verbatim copies of the Program's source code as you | |
197 | receive it, in any medium, provided that you conspicuously and | |
198 | appropriately publish on each copy an appropriate copyright notice; | |
199 | keep intact all notices stating that this License and any | |
200 | non-permissive terms added in accord with section 7 apply to the code; | |
201 | keep intact all notices of the absence of any warranty; and give all | |
202 | recipients a copy of this License along with the Program. | |
203 | ||
204 | You may charge any price or no price for each copy that you convey, | |
205 | and you may offer support or warranty protection for a fee. | |
206 | ||
207 | 5. Conveying Modified Source Versions. | |
208 | ||
209 | You may convey a work based on the Program, or the modifications to | |
210 | produce it from the Program, in the form of source code under the | |
211 | terms of section 4, provided that you also meet all of these conditions: | |
212 | ||
213 | a) The work must carry prominent notices stating that you modified | |
214 | it, and giving a relevant date. | |
215 | ||
216 | b) The work must carry prominent notices stating that it is | |
217 | released under this License and any conditions added under section | |
218 | 7. This requirement modifies the requirement in section 4 to | |
219 | "keep intact all notices". | |
220 | ||
221 | c) You must license the entire work, as a whole, under this | |
222 | License to anyone who comes into possession of a copy. This | |
223 | License will therefore apply, along with any applicable section 7 | |
224 | additional terms, to the whole of the work, and all its parts, | |
225 | regardless of how they are packaged. This License gives no | |
226 | permission to license the work in any other way, but it does not | |
227 | invalidate such permission if you have separately received it. | |
228 | ||
229 | d) If the work has interactive user interfaces, each must display | |
230 | Appropriate Legal Notices; however, if the Program has interactive | |
231 | interfaces that do not display Appropriate Legal Notices, your | |
232 | work need not make them do so. | |
233 | ||
234 | A compilation of a covered work with other separate and independent | |
235 | works, which are not by their nature extensions of the covered work, | |
236 | and which are not combined with it such as to form a larger program, | |
237 | in or on a volume of a storage or distribution medium, is called an | |
238 | "aggregate" if the compilation and its resulting copyright are not | |
239 | used to limit the access or legal rights of the compilation's users | |
240 | beyond what the individual works permit. Inclusion of a covered work | |
241 | in an aggregate does not cause this License to apply to the other | |
242 | parts of the aggregate. | |
243 | ||
244 | 6. Conveying Non-Source Forms. | |
245 | ||
246 | You may convey a covered work in object code form under the terms | |
247 | of sections 4 and 5, provided that you also convey the | |
248 | machine-readable Corresponding Source under the terms of this License, | |
249 | in one of these ways: | |
250 | ||
251 | a) Convey the object code in, or embodied in, a physical product | |
252 | (including a physical distribution medium), accompanied by the | |
253 | Corresponding Source fixed on a durable physical medium | |
254 | customarily used for software interchange. | |
255 | ||
256 | b) Convey the object code in, or embodied in, a physical product | |
257 | (including a physical distribution medium), accompanied by a | |
258 | written offer, valid for at least three years and valid for as | |
259 | long as you offer spare parts or customer support for that product | |
260 | model, to give anyone who possesses the object code either (1) a | |
261 | copy of the Corresponding Source for all the software in the | |
262 | product that is covered by this License, on a durable physical | |
263 | medium customarily used for software interchange, for a price no | |
264 | more than your reasonable cost of physically performing this | |
265 | conveying of source, or (2) access to copy the | |
266 | Corresponding Source from a network server at no charge. | |
267 | ||
268 | c) Convey individual copies of the object code with a copy of the | |
269 | written offer to provide the Corresponding Source. This | |
270 | alternative is allowed only occasionally and noncommercially, and | |
271 | only if you received the object code with such an offer, in accord | |
272 | with subsection 6b. | |
273 | ||
274 | d) Convey the object code by offering access from a designated | |
275 | place (gratis or for a charge), and offer equivalent access to the | |
276 | Corresponding Source in the same way through the same place at no | |
277 | further charge. You need not require recipients to copy the | |
278 | Corresponding Source along with the object code. If the place to | |
279 | copy the object code is a network server, the Corresponding Source | |
280 | may be on a different server (operated by you or a third party) | |
281 | that supports equivalent copying facilities, provided you maintain | |
282 | clear directions next to the object code saying where to find the | |
283 | Corresponding Source. Regardless of what server hosts the | |
284 | Corresponding Source, you remain obligated to ensure that it is | |
285 | available for as long as needed to satisfy these requirements. | |
286 | ||
287 | e) Convey the object code using peer-to-peer transmission, provided | |
288 | you inform other peers where the object code and Corresponding | |
289 | Source of the work are being offered to the general public at no | |
290 | charge under subsection 6d. | |
291 | ||
292 | A separable portion of the object code, whose source code is excluded | |
293 | from the Corresponding Source as a System Library, need not be | |
294 | included in conveying the object code work. | |
295 | ||
296 | A "User Product" is either (1) a "consumer product", which means any | |
297 | tangible personal property which is normally used for personal, family, | |
298 | or household purposes, or (2) anything designed or sold for incorporation | |
299 | into a dwelling. In determining whether a product is a consumer product, | |
300 | doubtful cases shall be resolved in favor of coverage. For a particular | |
301 | product received by a particular user, "normally used" refers to a | |
302 | typical or common use of that class of product, regardless of the status | |
303 | of the particular user or of the way in which the particular user | |
304 | actually uses, or expects or is expected to use, the product. A product | |
305 | is a consumer product regardless of whether the product has substantial | |
306 | commercial, industrial or non-consumer uses, unless such uses represent | |
307 | the only significant mode of use of the product. | |
308 | ||
309 | "Installation Information" for a User Product means any methods, | |
310 | procedures, authorization keys, or other information required to install | |
311 | and execute modified versions of a covered work in that User Product from | |
312 | a modified version of its Corresponding Source. The information must | |
313 | suffice to ensure that the continued functioning of the modified object | |
314 | code is in no case prevented or interfered with solely because | |
315 | modification has been made. | |
316 | ||
317 | If you convey an object code work under this section in, or with, or | |
318 | specifically for use in, a User Product, and the conveying occurs as | |
319 | part of a transaction in which the right of possession and use of the | |
320 | User Product is transferred to the recipient in perpetuity or for a | |
321 | fixed term (regardless of how the transaction is characterized), the | |
322 | Corresponding Source conveyed under this section must be accompanied | |
323 | by the Installation Information. But this requirement does not apply | |
324 | if neither you nor any third party retains the ability to install | |
325 | modified object code on the User Product (for example, the work has | |
326 | been installed in ROM). | |
327 | ||
328 | The requirement to provide Installation Information does not include a | |
329 | requirement to continue to provide support service, warranty, or updates | |
330 | for a work that has been modified or installed by the recipient, or for | |
331 | the User Product in which it has been modified or installed. Access to a | |
332 | network may be denied when the modification itself materially and | |
333 | adversely affects the operation of the network or violates the rules and | |
334 | protocols for communication across the network. | |
335 | ||
336 | Corresponding Source conveyed, and Installation Information provided, | |
337 | in accord with this section must be in a format that is publicly | |
338 | documented (and with an implementation available to the public in | |
339 | source code form), and must require no special password or key for | |
340 | unpacking, reading or copying. | |
341 | ||
342 | 7. Additional Terms. | |
343 | ||
344 | "Additional permissions" are terms that supplement the terms of this | |
345 | License by making exceptions from one or more of its conditions. | |
346 | Additional permissions that are applicable to the entire Program shall | |
347 | be treated as though they were included in this License, to the extent | |
348 | that they are valid under applicable law. If additional permissions | |
349 | apply only to part of the Program, that part may be used separately | |
350 | under those permissions, but the entire Program remains governed by | |
351 | this License without regard to the additional permissions. | |
352 | ||
353 | When you convey a copy of a covered work, you may at your option | |
354 | remove any additional permissions from that copy, or from any part of | |
355 | it. (Additional permissions may be written to require their own | |
356 | removal in certain cases when you modify the work.) You may place | |
357 | additional permissions on material, added by you to a covered work, | |
358 | for which you have or can give appropriate copyright permission. | |
359 | ||
360 | Notwithstanding any other provision of this License, for material you | |
361 | add to a covered work, you may (if authorized by the copyright holders of | |
362 | that material) supplement the terms of this License with terms: | |
363 | ||
364 | a) Disclaiming warranty or limiting liability differently from the | |
365 | terms of sections 15 and 16 of this License; or | |
366 | ||
367 | b) Requiring preservation of specified reasonable legal notices or | |
368 | author attributions in that material or in the Appropriate Legal | |
369 | Notices displayed by works containing it; or | |
370 | ||
371 | c) Prohibiting misrepresentation of the origin of that material, or | |
372 | requiring that modified versions of such material be marked in | |
373 | reasonable ways as different from the original version; or | |
374 | ||
375 | d) Limiting the use for publicity purposes of names of licensors or | |
376 | authors of the material; or | |
377 | ||
378 | e) Declining to grant rights under trademark law for use of some | |
379 | trade names, trademarks, or service marks; or | |
380 | ||
381 | f) Requiring indemnification of licensors and authors of that | |
382 | material by anyone who conveys the material (or modified versions of | |
383 | it) with contractual assumptions of liability to the recipient, for | |
384 | any liability that these contractual assumptions directly impose on | |
385 | those licensors and authors. | |
386 | ||
387 | All other non-permissive additional terms are considered "further | |
388 | restrictions" within the meaning of section 10. If the Program as you | |
389 | received it, or any part of it, contains a notice stating that it is | |
390 | governed by this License along with a term that is a further | |
391 | restriction, you may remove that term. If a license document contains | |
392 | a further restriction but permits relicensing or conveying under this | |
393 | License, you may add to a covered work material governed by the terms | |
394 | of that license document, provided that the further restriction does | |
395 | not survive such relicensing or conveying. | |
396 | ||
397 | If you add terms to a covered work in accord with this section, you | |
398 | must place, in the relevant source files, a statement of the | |
399 | additional terms that apply to those files, or a notice indicating | |
400 | where to find the applicable terms. | |
401 | ||
402 | Additional terms, permissive or non-permissive, may be stated in the | |
403 | form of a separately written license, or stated as exceptions; | |
404 | the above requirements apply either way. | |
405 | ||
406 | 8. Termination. | |
407 | ||
408 | You may not propagate or modify a covered work except as expressly | |
409 | provided under this License. Any attempt otherwise to propagate or | |
410 | modify it is void, and will automatically terminate your rights under | |
411 | this License (including any patent licenses granted under the third | |
412 | paragraph of section 11). | |
413 | ||
414 | However, if you cease all violation of this License, then your | |
415 | license from a particular copyright holder is reinstated (a) | |
416 | provisionally, unless and until the copyright holder explicitly and | |
417 | finally terminates your license, and (b) permanently, if the copyright | |
418 | holder fails to notify you of the violation by some reasonable means | |
419 | prior to 60 days after the cessation. | |
420 | ||
421 | Moreover, your license from a particular copyright holder is | |
422 | reinstated permanently if the copyright holder notifies you of the | |
423 | violation by some reasonable means, this is the first time you have | |
424 | received notice of violation of this License (for any work) from that | |
425 | copyright holder, and you cure the violation prior to 30 days after | |
426 | your receipt of the notice. | |
427 | ||
428 | Termination of your rights under this section does not terminate the | |
429 | licenses of parties who have received copies or rights from you under | |
430 | this License. If your rights have been terminated and not permanently | |
431 | reinstated, you do not qualify to receive new licenses for the same | |
432 | material under section 10. | |
433 | ||
434 | 9. Acceptance Not Required for Having Copies. | |
435 | ||
436 | You are not required to accept this License in order to receive or | |
437 | run a copy of the Program. Ancillary propagation of a covered work | |
438 | occurring solely as a consequence of using peer-to-peer transmission | |
439 | to receive a copy likewise does not require acceptance. However, | |
440 | nothing other than this License grants you permission to propagate or | |
441 | modify any covered work. These actions infringe copyright if you do | |
442 | not accept this License. Therefore, by modifying or propagating a | |
443 | covered work, you indicate your acceptance of this License to do so. | |
444 | ||
445 | 10. Automatic Licensing of Downstream Recipients. | |
446 | ||
447 | Each time you convey a covered work, the recipient automatically | |
448 | receives a license from the original licensors, to run, modify and | |
449 | propagate that work, subject to this License. You are not responsible | |
450 | for enforcing compliance by third parties with this License. | |
451 | ||
452 | An "entity transaction" is a transaction transferring control of an | |
453 | organization, or substantially all assets of one, or subdividing an | |
454 | organization, or merging organizations. If propagation of a covered | |
455 | work results from an entity transaction, each party to that | |
456 | transaction who receives a copy of the work also receives whatever | |
457 | licenses to the work the party's predecessor in interest had or could | |
458 | give under the previous paragraph, plus a right to possession of the | |
459 | Corresponding Source of the work from the predecessor in interest, if | |
460 | the predecessor has it or can get it with reasonable efforts. | |
461 | ||
462 | You may not impose any further restrictions on the exercise of the | |
463 | rights granted or affirmed under this License. For example, you may | |
464 | not impose a license fee, royalty, or other charge for exercise of | |
465 | rights granted under this License, and you may not initiate litigation | |
466 | (including a cross-claim or counterclaim in a lawsuit) alleging that | |
467 | any patent claim is infringed by making, using, selling, offering for | |
468 | sale, or importing the Program or any portion of it. | |
469 | ||
470 | 11. Patents. | |
471 | ||
472 | A "contributor" is a copyright holder who authorizes use under this | |
473 | License of the Program or a work on which the Program is based. The | |
474 | work thus licensed is called the contributor's "contributor version". | |
475 | ||
476 | A contributor's "essential patent claims" are all patent claims | |
477 | owned or controlled by the contributor, whether already acquired or | |
478 | hereafter acquired, that would be infringed by some manner, permitted | |
479 | by this License, of making, using, or selling its contributor version, | |
480 | but do not include claims that would be infringed only as a | |
481 | consequence of further modification of the contributor version. For | |
482 | purposes of this definition, "control" includes the right to grant | |
483 | patent sublicenses in a manner consistent with the requirements of | |
484 | this License. | |
485 | ||
486 | Each contributor grants you a non-exclusive, worldwide, royalty-free | |
487 | patent license under the contributor's essential patent claims, to | |
488 | make, use, sell, offer for sale, import and otherwise run, modify and | |
489 | propagate the contents of its contributor version. | |
490 | ||
491 | In the following three paragraphs, a "patent license" is any express | |
492 | agreement or commitment, however denominated, not to enforce a patent | |
493 | (such as an express permission to practice a patent or covenant not to | |
494 | sue for patent infringement). To "grant" such a patent license to a | |
495 | party means to make such an agreement or commitment not to enforce a | |
496 | patent against the party. | |
497 | ||
498 | If you convey a covered work, knowingly relying on a patent license, | |
499 | and the Corresponding Source of the work is not available for anyone | |
500 | to copy, free of charge and under the terms of this License, through a | |
501 | publicly available network server or other readily accessible means, | |
502 | then you must either (1) cause the Corresponding Source to be so | |
503 | available, or (2) arrange to deprive yourself of the benefit of the | |
504 | patent license for this particular work, or (3) arrange, in a manner | |
505 | consistent with the requirements of this License, to extend the patent | |
506 | license to downstream recipients. "Knowingly relying" means you have | |
507 | actual knowledge that, but for the patent license, your conveying the | |
508 | covered work in a country, or your recipient's use of the covered work | |
509 | in a country, would infringe one or more identifiable patents in that | |
510 | country that you have reason to believe are valid. | |
511 | ||
512 | If, pursuant to or in connection with a single transaction or | |
513 | arrangement, you convey, or propagate by procuring conveyance of, a | |
514 | covered work, and grant a patent license to some of the parties | |
515 | receiving the covered work authorizing them to use, propagate, modify | |
516 | or convey a specific copy of the covered work, then the patent license | |
517 | you grant is automatically extended to all recipients of the covered | |
518 | work and works based on it. | |
519 | ||
520 | A patent license is "discriminatory" if it does not include within | |
521 | the scope of its coverage, prohibits the exercise of, or is | |
522 | conditioned on the non-exercise of one or more of the rights that are | |
523 | specifically granted under this License. You may not convey a covered | |
524 | work if you are a party to an arrangement with a third party that is | |
525 | in the business of distributing software, under which you make payment | |
526 | to the third party based on the extent of your activity of conveying | |
527 | the work, and under which the third party grants, to any of the | |
528 | parties who would receive the covered work from you, a discriminatory | |
529 | patent license (a) in connection with copies of the covered work | |
530 | conveyed by you (or copies made from those copies), or (b) primarily | |
531 | for and in connection with specific products or compilations that | |
532 | contain the covered work, unless you entered into that arrangement, | |
533 | or that patent license was granted, prior to 28 March 2007. | |
534 | ||
535 | Nothing in this License shall be construed as excluding or limiting | |
536 | any implied license or other defenses to infringement that may | |
537 | otherwise be available to you under applicable patent law. | |
538 | ||
539 | 12. No Surrender of Others' Freedom. | |
540 | ||
541 | If conditions are imposed on you (whether by court order, agreement or | |
542 | otherwise) that contradict the conditions of this License, they do not | |
543 | excuse you from the conditions of this License. If you cannot convey a | |
544 | covered work so as to satisfy simultaneously your obligations under this | |
545 | License and any other pertinent obligations, then as a consequence you may | |
546 | not convey it at all. For example, if you agree to terms that obligate you | |
547 | to collect a royalty for further conveying from those to whom you convey | |
548 | the Program, the only way you could satisfy both those terms and this | |
549 | License would be to refrain entirely from conveying the Program. | |
550 | ||
551 | 13. Use with the GNU Affero General Public License. | |
552 | ||
553 | Notwithstanding any other provision of this License, you have | |
554 | permission to link or combine any covered work with a work licensed | |
555 | under version 3 of the GNU Affero General Public License into a single | |
556 | combined work, and to convey the resulting work. The terms of this | |
557 | License will continue to apply to the part which is the covered work, | |
558 | but the special requirements of the GNU Affero General Public License, | |
559 | section 13, concerning interaction through a network will apply to the | |
560 | combination as such. | |
561 | ||
562 | 14. Revised Versions of this License. | |
563 | ||
564 | The Free Software Foundation may publish revised and/or new versions of | |
565 | the GNU General Public License from time to time. Such new versions will | |
566 | be similar in spirit to the present version, but may differ in detail to | |
567 | address new problems or concerns. | |
568 | ||
569 | Each version is given a distinguishing version number. If the | |
570 | Program specifies that a certain numbered version of the GNU General | |
571 | Public License "or any later version" applies to it, you have the | |
572 | option of following the terms and conditions either of that numbered | |
573 | version or of any later version published by the Free Software | |
574 | Foundation. If the Program does not specify a version number of the | |
575 | GNU General Public License, you may choose any version ever published | |
576 | by the Free Software Foundation. | |
577 | ||
578 | If the Program specifies that a proxy can decide which future | |
579 | versions of the GNU General Public License can be used, that proxy's | |
580 | public statement of acceptance of a version permanently authorizes you | |
581 | to choose that version for the Program. | |
582 | ||
583 | Later license versions may give you additional or different | |
584 | permissions. However, no additional obligations are imposed on any | |
585 | author or copyright holder as a result of your choosing to follow a | |
586 | later version. | |
587 | ||
588 | 15. Disclaimer of Warranty. | |
589 | ||
590 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY | |
591 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT | |
592 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY | |
593 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, | |
594 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR | |
595 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM | |
596 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF | |
597 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. | |
598 | ||
599 | 16. Limitation of Liability. | |
600 | ||
601 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | |
602 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS | |
603 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY | |
604 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE | |
605 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF | |
606 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD | |
607 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), | |
608 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF | |
609 | SUCH DAMAGES. | |
610 | ||
611 | 17. Interpretation of Sections 15 and 16. | |
612 | ||
613 | If the disclaimer of warranty and limitation of liability provided | |
614 | above cannot be given local legal effect according to their terms, | |
615 | reviewing courts shall apply local law that most closely approximates | |
616 | an absolute waiver of all civil liability in connection with the | |
617 | Program, unless a warranty or assumption of liability accompanies a | |
618 | copy of the Program in return for a fee. | |
619 | ||
620 | END OF TERMS AND CONDITIONS |
0 | Metadata-Version: 1.1 | |
1 | Name: asset | |
2 | Version: 0.6.13 | |
3 | Summary: A package resource and symbol loading helper library. | |
4 | Home-page: http://github.com/metagriffin/asset | |
5 | Author: metagriffin | |
6 | Author-email: [email protected] | |
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 | Keywords: python package pkg_resources asset resolve lookup loader | |
190 | Platform: any | |
191 | Classifier: Development Status :: 5 - Production/Stable | |
192 | Classifier: Intended Audience :: Developers | |
193 | Classifier: Programming Language :: Python | |
194 | Classifier: Operating System :: OS Independent | |
195 | Classifier: Natural Language :: English | |
196 | Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+) |
0 | ================================ | |
1 | Generalized Package Asset Loader | |
2 | ================================ | |
3 | ||
4 | Loads resources and symbols from a python package, whether installed | |
5 | as a directory, an egg, or in source form. Also provides some other | |
6 | package-related helper methods, including ``asset.version()``, | |
7 | ``asset.caller()``, and ``asset.chunks()``. | |
8 | ||
9 | TL;DR | |
10 | ===== | |
11 | ||
12 | Install: | |
13 | ||
14 | .. code:: bash | |
15 | ||
16 | $ pip install asset | |
17 | ||
18 | Load symbols (e.g. functions, classes, or variables) from a package by | |
19 | name: | |
20 | ||
21 | .. code:: python | |
22 | ||
23 | import asset | |
24 | ||
25 | # load the 'mypackage.foo.myfunc' function and call it with some parameter | |
26 | retval = asset.symbol('mypackage.foo.myfunc')(param='value') | |
27 | ||
28 | Load data files from a package: | |
29 | ||
30 | .. code:: python | |
31 | ||
32 | # load the file 'mypackage/templates/data.txt' into string | |
33 | data = asset.load('mypackage:templates/data.txt').read() | |
34 | ||
35 | # or as a file-like stream | |
36 | stream = asset.load('mypackage:templates/data.txt').stream() | |
37 | data = stream.read() | |
38 | ||
39 | Multiple files can be operated on at once by using `globre | |
40 | <https://pypi.python.org/pypi/globre>`_ style wildcards: | |
41 | ||
42 | .. code:: python | |
43 | ||
44 | # concatenate all 'css' files into one string: | |
45 | css = asset.load('mypackage:static/style/**.css').read() | |
46 | ||
47 | # load all '.txt' files, XML-escaping the data and wrapping | |
48 | # each file in an <node name="...">...</node> element. | |
49 | import xml.etree.ElementTree as ET | |
50 | data = ET.Element('nodes') | |
51 | for item in asset.load('asset:**.txt'): | |
52 | cur = ET.SubElement(data, 'node', name=item.name) | |
53 | cur.text = item.read() | |
54 | data = ET.tostring(data) | |
55 | ||
56 | Query the installed version of a package: | |
57 | ||
58 | .. code:: python | |
59 | ||
60 | asset.version('asset') | |
61 | # ==> '0.0.5' | |
62 | ||
63 | asset.version('python') | |
64 | # ==> '2.7' | |
65 | ||
66 | asset.version('no-such-package') | |
67 | # ==> None | |
68 | ||
69 | Find out what package is calling the current function: | |
70 | ||
71 | .. code:: python | |
72 | ||
73 | # assuming the call stack is: | |
74 | # in package "zig" a function "x", which calls | |
75 | # in package "bar" a function "y", which calls | |
76 | # in package "foo" a function "callfoo" defined as: | |
77 | ||
78 | def callfoo(): | |
79 | ||
80 | asset.caller() | |
81 | # ==> 'bar' | |
82 | ||
83 | asset.caller(ignore='bar') | |
84 | # ==> 'zig' | |
85 | ||
86 | asset.caller(ignore=['bar', 'zig']) | |
87 | # ==> None | |
88 | ||
89 | Call all the plugins for a given group: | |
90 | ||
91 | .. code:: python | |
92 | ||
93 | for plugin in asset.plugins('mypackage.plugins'): | |
94 | plugin.handle() | |
95 | ||
96 | Filter an object through all the plugins for a given group (if there | |
97 | are no plugins, this will simply return `thing`): | |
98 | ||
99 | .. code:: python | |
100 | ||
101 | result = asset.plugins('mypackage.plugins').filter(thing) | |
102 | ||
103 | Load all registered plugins, select the ones named `foo` and invoke | |
104 | them (this will fail if there is no `foo` plugin): | |
105 | ||
106 | .. code:: python | |
107 | ||
108 | result = asset.plugins('mypackage.plugins').select('foo').handle(thing) | |
109 | ||
110 | Chunk a file (or any file-like object) into 1 KiB chunks: | |
111 | ||
112 | .. code:: python | |
113 | ||
114 | with open('/var/binary/data', 'rb') as fp: | |
115 | for chunk in asset.chunks(fp, 1024): | |
116 | # ... do something with `chunk` ... | |
117 | ||
118 | Chunk an Asset stream (here using the `.chunks` alias method): | |
119 | ||
120 | .. code:: python | |
121 | ||
122 | for chunk in asset.load('mypackage:data/**.bin').chunks(): | |
123 | # ... using the default chunk size (usually 8 KiB) ... | |
124 | ||
125 | ||
126 | Testing | |
127 | ======= | |
128 | ||
129 | In order to run the unit tests correctly, the `pxml` package needs to | |
130 | be installed as a zipped package (i.e. an "egg") and the `globre` | |
131 | package needs to be installed unzipped. To accomplish that, do: | |
132 | ||
133 | .. code:: bash | |
134 | ||
135 | $ easy_install --zip-ok pxml | |
136 | $ easy_install --always-unzip globre | |
137 | ||
138 | The reason is that the unit tests confirm that `asset` can load assets | |
139 | from both zipped and unzipped packages, and can also identify in which | |
140 | mode it is operating. | |
141 | ||
142 | ||
143 | Details | |
144 | ======= | |
145 | ||
146 | TODO: add detailed docs... | |
147 | ||
148 | * ``Asset.filename``: | |
149 | ||
150 | If the asset represents a file on the filesystem, is the absolute | |
151 | path to the specified file. Otherwise is ``None``. | |
152 | ||
153 | * ``AssetGroupStream.readline()``: | |
154 | ||
155 | Returns the next line from the aggregate asset group stream, as if | |
156 | the assets had been concatenate into a single asset. | |
157 | ||
158 | **IMPORTANT**: if an asset ends with content that is not terminated | |
159 | by an EOL token, it is returned as-is, i.e. it does NOT append the | |
160 | first line from the next asset. | |
161 | ||
162 | Note: because ``asset.load()`` does lazy-loading, it only throws a | |
163 | `NoSuchAsset` exception when you actually attempt to use the | |
164 | AssetGroup! If you need an immediate error, use the `peek()` method. | |
165 | Note that it returns itself, so you can do something like: | |
166 | ||
167 | .. code:: python | |
168 | ||
169 | import asset | |
170 | ||
171 | def my_function_that_returns_an_iterable(): | |
172 | ||
173 | return asset.load(my_spec).peek() | |
174 | ||
175 | # this returns exactly the same thing as the following: | |
176 | # | |
177 | # return asset.load(my_spec) | |
178 | # | |
179 | # 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 | * make it easy to create a plugin helper, eg instead of: | |
12 | ||
13 | @asset.plugin('jstc.precompilers.plugins', 'text/x-easytpl') | |
14 | ...def-my-plugin... | |
15 | ||
16 | make it possible to do: | |
17 | ||
18 | @jstc.precompilers.plugin('text/x-easytpl') | |
19 | ...def-my-plugin... | |
20 | ||
21 | * add a context manager for ``with asset.load(...) as fp: ...`` | |
22 | ||
23 | * when you load relative plugins, they should default to the end | |
24 | unless explicit ordering is defined by the plugin. eg, given a | |
25 | standard plugin set of ('a', 'b') where 'b' specifies ``after='a'``, | |
26 | and the plugin spec '+foo.bar.method' is loaded, then | |
27 | the result is:: | |
28 | ||
29 | 'a', 'foo.bar.method', 'b' | |
30 | ||
31 | instead of:: | |
32 | ||
33 | 'a', 'b', 'foo.bar.method' | |
34 | ||
35 | * make a setup directive that can find and populate all | |
36 | `asset.plugin()` calls | |
37 | ||
38 | * make `asset.plugin()` calls check that the `group` starts | |
39 | with the caller's package for namespacing and if not issue | |
40 | a log.warning() | |
41 | ||
42 | * make NoSuchAsset subclass IOError?... | |
43 | ||
44 | * add support for "file://" paths so that asset() can be used | |
45 | agnostically to whether the asset is on the filesystem or | |
46 | in a python package... | |
47 | ||
48 | * add shortcuts... | |
49 | asset.read(*) == asset.load(*).read() | |
50 | ||
51 | * make .load() optimize for no-wildcards specs by returning an Asset. | |
52 | ==> Asset's must behave like AssetGroups though! (i.e. listable) | |
53 | ||
54 | * make import errors better, e.g. an | |
55 | asset.symbol('asset.badmodule.BadClass') | |
56 | ||
57 | fails with: | |
58 | ImportError: No module named badmodule | |
59 | ||
60 | or if badmodule exists, but not BadClass, then: | |
61 | ImportError: No module named BadClass | |
62 | ||
63 | it should: | |
64 | ImportError: No module named asset.badmodule | |
65 | ||
66 | for the former, and: | |
67 | ImportError: No module or attribute named asset.badmodule.BadClass | |
68 | ||
69 | for the latter. | |
70 | ||
71 | ==> perhaps return an AssetError which is subclass of both ImportError | |
72 | and AttributeError? | |
73 | no. just ImportError | |
74 | unless the asset-spec specifies an attribute... | |
75 | ||
76 | * make asset.load() complain on unknown keywords, such as `transformer` | |
77 | ||
78 | * convert the `peek()` method into a .load(lazy=True) parameter. | |
79 | ||
80 | * add helpers: | |
81 | * `isspec` | |
82 | * `isresource` | |
83 | * `issymbol` | |
84 | ||
85 | base it on:: | |
86 | ||
87 | import re | |
88 | isResourceSpec = re.compile('^[a-z][a-z0-9_]*:', re.IGNORECASE) | |
89 | def isresource(spec): | |
90 | return isstr(spec) and bool(isResourceSpec.match(spec)) | |
91 | ||
92 | * make the stream returned by asset.load(SPEC).stream() behave like a stream... | |
93 | not whatever this is: | |
94 | ||
95 | Traceback (most recent call last): | |
96 | File "/media/raspi-local/raspi-door.git/raspi_door/trap.py", line 59, in trigger | |
97 | target[2](*args, topic=topic, event=event, **kw) | |
98 | File "/media/raspi-local/raspi-door.git/raspi_door/sensor.py", line 120, in onSense | |
99 | self.sounds[evt] = pygame.mixer.Sound(play) | |
100 | error: OGG bitstream is not valid Vorbis stream! | |
101 |
0 | 0.6.13 |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2013/09/21 | |
5 | # copy: (C) Copyright 2013-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | from .symbol import * | |
22 | from .resource import * | |
23 | from .isstr import isstr | |
24 | from .plugin import plugin, plugins, PluginSet | |
25 | ||
26 | #------------------------------------------------------------------------------ | |
27 | # end of $Id$ | |
28 | #------------------------------------------------------------------------------ |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2013/09/22 | |
5 | # copy: (C) Copyright 2013-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | import six | |
22 | ||
23 | if six.PY3: | |
24 | def isstr(obj): | |
25 | return isinstance(obj, str) | |
26 | else: | |
27 | def isstr(obj): | |
28 | return isinstance(obj, basestring) | |
29 | ||
30 | #------------------------------------------------------------------------------ | |
31 | # end of $Id$ | |
32 | #------------------------------------------------------------------------------ |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2015/11/12 | |
5 | # copy: (C) Copyright 2015-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | import re | |
22 | import logging | |
23 | ||
24 | import six | |
25 | import pkg_resources | |
26 | from aadict import aadict | |
27 | from .symbol import symbol | |
28 | ||
29 | #------------------------------------------------------------------------------ | |
30 | ||
31 | log = logging.getLogger(__name__) | |
32 | ||
33 | #------------------------------------------------------------------------------ | |
34 | class PluginSet(object): | |
35 | ''' | |
36 | A PluginSet is a list of `Plugin` objects that can be iterated over | |
37 | to get each Plugin, but it also has some methods that operate on all | |
38 | plugins together. | |
39 | ''' | |
40 | ||
41 | #---------------------------------------------------------------------------- | |
42 | def __init__(self, group, spec, plugins, *args, **kw): | |
43 | super(PluginSet, self).__init__(*args, **kw) | |
44 | self.group = group | |
45 | self.spec = spec | |
46 | self.plugins = plugins or [] | |
47 | ||
48 | #---------------------------------------------------------------------------- | |
49 | def handle(self, object, *args, **kw): | |
50 | ''' | |
51 | Calls each plugin in this PluginSet with the specified object, | |
52 | arguments, and keywords in the standard group plugin order. The | |
53 | return value from each successive invoked plugin is passed as the | |
54 | first parameter to the next plugin. The final return value is the | |
55 | object returned from the last plugin. | |
56 | ||
57 | If this plugin set is empty (i.e. no plugins exist or matched the | |
58 | spec), then a ValueError exception is thrown. | |
59 | ''' | |
60 | if not bool(self): | |
61 | if not self.spec or self.spec == SPEC_ALL: | |
62 | raise ValueError('No plugins available in group %r' % (self.group,)) | |
63 | raise ValueError( | |
64 | 'No plugins in group %r matched %r' % (self.group, self.spec)) | |
65 | for plugin in self.plugins: | |
66 | object = plugin.handle(object, *args, **kw) | |
67 | return object | |
68 | ||
69 | #---------------------------------------------------------------------------- | |
70 | def filter(self, object, *args, **kw): | |
71 | ''' | |
72 | Identical to `PluginSet.handle`, except: | |
73 | ||
74 | #. If this plugin set is empty, `object` is returned as-is. | |
75 | #. If any plugin returns ``None``, it is returned without | |
76 | calling any further plugins. | |
77 | ''' | |
78 | for plugin in self.plugins: | |
79 | object = plugin.handle(object, *args, **kw) | |
80 | if object is None: | |
81 | return object | |
82 | return object | |
83 | ||
84 | #---------------------------------------------------------------------------- | |
85 | def select(self, name): | |
86 | ''' | |
87 | Returns a new PluginSet that has only the plugins in this that are | |
88 | named `name`. | |
89 | ''' | |
90 | return PluginSet(self.group, name, [ | |
91 | plug for plug in self.plugins if plug.name == name]) | |
92 | ||
93 | #---------------------------------------------------------------------------- | |
94 | def __bool__(self): | |
95 | return bool(self.plugins) | |
96 | ||
97 | #---------------------------------------------------------------------------- | |
98 | def __len__(self): | |
99 | return len(self.plugins) | |
100 | ||
101 | #---------------------------------------------------------------------------- | |
102 | def __iter__(self): | |
103 | return iter(self.plugins) | |
104 | ||
105 | #---------------------------------------------------------------------------- | |
106 | def __repr__(self): | |
107 | return '<PluginSet group=%r plugins=%r>' % ( | |
108 | self.group, [plug.name for plug in self.plugins]) | |
109 | ||
110 | #------------------------------------------------------------------------------ | |
111 | def plugins(group, spec=None): | |
112 | # TODO: share this documentation with `../doc/plugin.rst`... | |
113 | ''' | |
114 | Returns a `PluginSet` object for the specified setuptools-style | |
115 | entrypoint `group`. This is just a wrapper around | |
116 | `pkg_resources.iter_entry_points` that allows the plugins to sort | |
117 | and override themselves. | |
118 | ||
119 | The optional `spec` parameter controls how and what plugins are | |
120 | loaded. If it is ``None`` or the special value ``'*'``, then the | |
121 | normal plugin loading will occur, i.e. all registered plugins will | |
122 | be loaded and their self-declared ordering and dependencies will be | |
123 | applied. | |
124 | ||
125 | Otherwise, the `spec` is taken as a comma- or whitespace-separated | |
126 | list of plugins to load. In this mode, the `spec` can either specify | |
127 | an exact list of plugins to load, in the specified order, referred | |
128 | to as an "absolute" spec. Otherwise, it is a "relative" spec, which | |
129 | indicates that it only adjusts the standard registered plugin | |
130 | loading. A spec is a list of either absolute or relative | |
131 | instructions, and they cannot be mixed. | |
132 | ||
133 | In either mode, a plugin is identified either by name for registered | |
134 | plugins (e.g. ``foo``), or by fully-qualified Python module and | |
135 | symbol name for unregistered plugins | |
136 | (e.g. ``package.module.symbol``). | |
137 | ||
138 | Plugins in an absolute spec are loaded in the order specified and | |
139 | can be optionally prefixed with the following special characters: | |
140 | ||
141 | * ``'?'`` : the specified plugin should be loaded if available. If | |
142 | it is not registered, cannot be found, or cannot be loaded, then | |
143 | it is ignored (a DEBUG log message will be emitted, however). | |
144 | ||
145 | Plugins in a relative spec are always prefixed with at least one of | |
146 | the following special characters: | |
147 | ||
148 | * ``'-'`` : removes the specified plugin; this does not affect | |
149 | plugin ordering, it only removes the plugin from the loaded | |
150 | list. If the plugin does not exist, no error is thrown. | |
151 | ||
152 | * ``'+'`` : adds or requires the specified plugin to the loaded | |
153 | set. If the plugin is not a named/registered plugin, then it will | |
154 | be loaded as an asset-symbol, i.e. a Python-dotted module and | |
155 | symbol name. If the plugin does not exist or cannot be loaded, | |
156 | this will throw an error. It does not affect the plugin ordering | |
157 | of registered plugins. | |
158 | ||
159 | * ``'/'`` : the plugin name is taken as a regular expression that | |
160 | will be used to match plugin names and it must terminate in a | |
161 | slash. Note that this must be the **last** element in the spec | |
162 | list. | |
163 | ||
164 | Examples: | |
165 | ||
166 | * ``'*'`` : load all registered plugins. | |
167 | ||
168 | * ``'foo,bar'`` : load the "foo" plugin, then the "bar" plugin. | |
169 | ||
170 | * ``'foo,?bar'`` : load the "foo" plugin and if the "bar" plugin | |
171 | exists, load it too. | |
172 | ||
173 | * ``'-zig'`` : load all registered plugins except the "zig" plugin. | |
174 | ||
175 | * ``'+pkg.foo.bar'`` : load all registered plugins and then load | |
176 | the "pkg.foo.bar" Python symbol. | |
177 | ||
178 | * ``'pkg.foo.bar'`` : load only the "pkg.foo.bar" Python symbol. | |
179 | ''' | |
180 | pspec = _parse_spec(spec) | |
181 | plugs = list(_get_registered_plugins(group, pspec)) | |
182 | plugs += list(_get_unregistered_plugins(group, plugs, pspec)) | |
183 | return PluginSet(group, spec, list(_sort_plugins(group, plugs, pspec, spec))) | |
184 | ||
185 | #------------------------------------------------------------------------------ | |
186 | # relative specs: | |
187 | SPEC_ADD = '+' | |
188 | SPEC_REM = '-' | |
189 | SPEC_RE = '/' | |
190 | # absolute specs: | |
191 | SPEC_SET = ' ' | |
192 | SPEC_OPT = '?' | |
193 | SPEC_ALL = '*' | |
194 | _specsep_cre = re.compile(r'(^|\s+)([-+?])\s*') | |
195 | _specname_cre = re.compile(r'^[a-zA-Z_]') | |
196 | _spec_rel = set((SPEC_ADD, SPEC_REM, SPEC_RE)) | |
197 | _spec_abs = set((SPEC_SET, SPEC_OPT)) | |
198 | ||
199 | #------------------------------------------------------------------------------ | |
200 | def _parse_spec(spec): | |
201 | if isinstance(spec, tuple): | |
202 | return spec | |
203 | wspec = spec.strip() if spec else None | |
204 | if not wspec or wspec == SPEC_ALL: | |
205 | return () | |
206 | respec = None | |
207 | if wspec.endswith('/'): | |
208 | if len(wspec.split('/')) <= 2: | |
209 | raise ValueError( | |
210 | 'regex plugin loading expression must start and end with "/"') | |
211 | wspec, respec = wspec.split('/', 1) | |
212 | respec = respec[:-1] | |
213 | if wspec.strip() \ | |
214 | and not ( wspec.strip().endswith(',') or wspec != wspec.rstrip() ): | |
215 | raise ValueError( | |
216 | 'regex plugin loading expression must start and end with "/"') | |
217 | wspec = wspec.replace(',', ' ') | |
218 | wspec = _specsep_cre.sub(r' \2', wspec) | |
219 | wspec = [e.strip() for e in wspec.split()] | |
220 | ret = [] | |
221 | for item in wspec: | |
222 | if not item.strip(): | |
223 | continue | |
224 | item = aadict(op=SPEC_SET, target=item) | |
225 | if item.target and item.target[0] in (SPEC_ADD, SPEC_REM, SPEC_OPT): | |
226 | item = aadict(op=item.target[0], target=item.target[1:].strip()) | |
227 | if item.target and item.target[0] in (SPEC_RE,): | |
228 | raise ValueError( | |
229 | 'regex plugin loading expression must start and end with "/"') | |
230 | if not _specname_cre.match(item.target): | |
231 | raise ValueError( | |
232 | 'invalid plugin name in specification expression: %r' % (item.target,)) | |
233 | ret.append(item) | |
234 | if respec: | |
235 | ret.append(aadict(op=SPEC_RE, target=re.compile(respec))) | |
236 | ops = set([item.op for item in ret]) | |
237 | rel = ops & _spec_rel | |
238 | abs = ops & _spec_abs | |
239 | if bool(ops & rel) and bool(ops & abs): | |
240 | raise ValueError( | |
241 | 'invalid mixing of relative (%r) and absolute (%r) prefixes in plugin specification' | |
242 | % (list(rel), list(abs))) | |
243 | return tuple(ret) | |
244 | ||
245 | #------------------------------------------------------------------------------ | |
246 | def _match_spec(spec, name): | |
247 | if not spec: | |
248 | return True | |
249 | for idx, item in enumerate(spec): | |
250 | if item.op == SPEC_RE: | |
251 | if item.target.match(name): | |
252 | return True | |
253 | if ( idx + 1 ) >= len(spec): | |
254 | return False | |
255 | continue | |
256 | if item.target != name: | |
257 | continue | |
258 | if item.op == SPEC_REM: | |
259 | return False | |
260 | return True | |
261 | if spec[0].op in _spec_rel: | |
262 | return True | |
263 | return False | |
264 | ||
265 | #------------------------------------------------------------------------------ | |
266 | def _decorate_plugin(plugin): | |
267 | plugin.after = getattr(plugin.handle, 'after', None) | |
268 | plugin.before = getattr(plugin.handle, 'before', None) | |
269 | plugin.order = getattr(plugin.handle, 'order', 0) | |
270 | plugin.replace = getattr(plugin.handle, 'replace', False) | |
271 | plugin.final = getattr(plugin.handle, 'final', False) | |
272 | plugin.name = getattr(plugin.handle, 'plugin_name', plugin.name) | |
273 | ||
274 | #------------------------------------------------------------------------------ | |
275 | def _get_registered_plugins(group, spec=None): | |
276 | spec = _parse_spec(spec) | |
277 | for entrypoint in pkg_resources.iter_entry_points(group): | |
278 | plugin = aadict( | |
279 | name = entrypoint.name, | |
280 | entrypoint = entrypoint, | |
281 | ) | |
282 | if _match_spec(spec, plugin.name): | |
283 | try: | |
284 | plugin.handle = entrypoint.load() | |
285 | except ImportError as err: | |
286 | log.exception( | |
287 | 'Could not load plugin "%s" in group "%s": %s', | |
288 | entrypoint.name, group, str(err)) | |
289 | raise | |
290 | _decorate_plugin(plugin) | |
291 | yield plugin | |
292 | ||
293 | #------------------------------------------------------------------------------ | |
294 | def _load_asset_plugin(spec): | |
295 | plugin = aadict( | |
296 | name = spec.target, | |
297 | entrypoint = None, | |
298 | handle = symbol(spec.target), | |
299 | ) | |
300 | _decorate_plugin(plugin) | |
301 | if plugin.name != spec.target: | |
302 | # todo: this is a hack so that plugins can be loaded by their | |
303 | # dotted path, BUT they can declare themselves with a different | |
304 | # name. the effect here is that `_load_asset_plugin` has the side | |
305 | # effect of updating the spec to the declared name... | |
306 | # this is only needed in *very* odd circumstances... | |
307 | # the "right" way to do this is for the `spec` to only be applied | |
308 | # once, during load, so that if it specifies the load of a | |
309 | # dotted path, it will never be re-tested... ugh. | |
310 | spec.target = plugin.name | |
311 | return plugin | |
312 | ||
313 | #------------------------------------------------------------------------------ | |
314 | def _get_unregistered_plugins(group, plugins, spec=None): | |
315 | spec = _parse_spec(spec) | |
316 | names = [plug.name for plug in plugins] | |
317 | for item in spec: | |
318 | if item.op in (SPEC_REM, SPEC_RE) or item.target in names: | |
319 | continue | |
320 | try: | |
321 | yield _load_asset_plugin(item) | |
322 | except Exception: | |
323 | if item.op in (SPEC_OPT,): | |
324 | log.debug('could not load optional plugin %r', item.target) | |
325 | continue | |
326 | raise ValueError('could not load plugin %r' % (item.target,)) | |
327 | ||
328 | #------------------------------------------------------------------------------ | |
329 | def _sort_plugins(group, plugins, spec=None, ospec=None): | |
330 | spec = _parse_spec(spec) | |
331 | lut = dict() | |
332 | for plugin in plugins: | |
333 | if plugin.name not in lut: | |
334 | lut[plugin.name] = [] | |
335 | lut[plugin.name].append(plugin) | |
336 | # order the plugins within each named group by order/replace/final | |
337 | for name, plugs in list(lut.items()): | |
338 | plugs = sorted(plugs, key=lambda plug: plug.order) | |
339 | for idx, plug in enumerate(plugs): | |
340 | if plug.final: | |
341 | plugs = plugs[:idx + 1] | |
342 | break | |
343 | for idx, plug in enumerate(reversed(plugs)): | |
344 | if plug.replace: | |
345 | plugs = plugs[len(plugs) - idx - 1:] | |
346 | lut[name] = plugs | |
347 | # apply `spec` | |
348 | names = sorted(set( | |
349 | [name for name in lut.keys() if _match_spec(spec, name)])) | |
350 | if spec and spec[0].op not in _spec_rel: | |
351 | snames = [] | |
352 | for item in spec: | |
353 | if item.target in names: | |
354 | if item.target not in snames: | |
355 | snames.append(item.target) | |
356 | continue | |
357 | if item.op == SPEC_OPT: | |
358 | continue | |
359 | raise TypeError( | |
360 | '%s plugin spec %r specified unavailable dependency %r' | |
361 | % (group, ospec or spec, item.target)) | |
362 | for name in snames: | |
363 | for plug in lut[name]: | |
364 | yield plug | |
365 | return | |
366 | # order the named groups by after/before | |
367 | reqs = dict() | |
368 | for name in names: | |
369 | reqs[name] = aadict(after=[], before=[]) | |
370 | for plug in lut[name]: | |
371 | if plug.after: | |
372 | reqs[name].after += [p.strip() for p in plug.after.split(',')] | |
373 | if plug.before: | |
374 | reqs[name].before += [p.strip() for p in plug.before.split(',')] | |
375 | reqs[name].after = [aft for aft in reqs[name].after if aft] | |
376 | reqs[name].before = [bef for bef in reqs[name].before if bef] | |
377 | # simplify after/before evaluation by pushing before's into after's | |
378 | for name in names: | |
379 | for aft in reqs[name].after: | |
380 | opt = aft.startswith(SPEC_OPT) | |
381 | if not opt and aft not in names: | |
382 | raise TypeError( | |
383 | '%s plugin type %r specified unavailable \'after\' dependency %r' | |
384 | % (group, name, aft)) | |
385 | for bef in reqs[name].before: | |
386 | opt = bef.startswith(SPEC_OPT) | |
387 | if opt: | |
388 | bef = bef[1:] | |
389 | if bef not in names: | |
390 | if not opt: | |
391 | raise TypeError( | |
392 | '%s plugin type %r specified unavailable \'before\' dependency %r' | |
393 | % (group, name, bef)) | |
394 | continue | |
395 | reqs[bef].after.append(name) | |
396 | # created the ordered list obeying the 'after' rules | |
397 | snames = [] | |
398 | while len(snames) < len(names): | |
399 | cur = len(snames) | |
400 | for name in names: | |
401 | if name in snames: | |
402 | continue | |
403 | ok = True | |
404 | for aft in reqs[name].after: | |
405 | opt = aft.startswith(SPEC_OPT) | |
406 | if opt: | |
407 | aft = aft[1:] | |
408 | if aft not in snames and aft in names: | |
409 | ok = False | |
410 | if ok: | |
411 | snames.append(name) | |
412 | if len(snames) == cur: | |
413 | raise TypeError( | |
414 | '%s has cyclical dependencies in plugins %r' | |
415 | % (group, sorted(list(set(names) - set(snames))),)) | |
416 | for name in snames: | |
417 | for plug in lut[name]: | |
418 | yield plug | |
419 | ||
420 | #------------------------------------------------------------------------------ | |
421 | def plugin(group, name, after=None, before=None, order=None, replace=None, final=None): | |
422 | def _wrapper(func): | |
423 | func.plugin_group = group | |
424 | func.plugin_name = name | |
425 | if after is not None: | |
426 | func.after = after | |
427 | if before is not None: | |
428 | func.before = before | |
429 | if order is not None: | |
430 | func.order = order | |
431 | if replace is not None: | |
432 | func.replace = replace | |
433 | if final is not None: | |
434 | func.final = final | |
435 | return func | |
436 | return _wrapper | |
437 | ||
438 | #------------------------------------------------------------------------------ | |
439 | # end of $Id$ | |
440 | # $ChangeLog$ | |
441 | #------------------------------------------------------------------------------ |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2013/09/22 | |
5 | # copy: (C) Copyright 2013-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | import re | |
22 | import os | |
23 | import functools | |
24 | ||
25 | import pkg_resources | |
26 | import six | |
27 | import globre | |
28 | ||
29 | from .symbol import symbol | |
30 | ||
31 | #------------------------------------------------------------------------------ | |
32 | ||
33 | MAXBUF = 8192 | |
34 | ||
35 | #------------------------------------------------------------------------------ | |
36 | class NoSuchAsset(Exception): pass | |
37 | ||
38 | ||
39 | #------------------------------------------------------------------------------ | |
40 | class AssetGroupStream(object): | |
41 | # TODO: implement all expected file-like methods... | |
42 | def __init__(self, group): | |
43 | self.group = group | |
44 | self.assets = iter(group) | |
45 | self._cur = None | |
46 | def read(self, size=-1): | |
47 | ret = b'' if self._cur is None else self._cur.read(size) | |
48 | if size >= 0 and len(ret) >= size: | |
49 | return ret | |
50 | while True: | |
51 | try: | |
52 | self._cur = six.next(self.assets) | |
53 | except StopIteration: | |
54 | self._cur = None | |
55 | return ret | |
56 | ret += self._cur.read(( size - len(ret) ) if size > 0 else -1) | |
57 | if size >= 0 and len(ret) >= size: | |
58 | return ret | |
59 | def readline(self): | |
60 | if self._cur is None: | |
61 | try: | |
62 | self._cur = six.next(self.assets) | |
63 | except StopIteration: | |
64 | self._cur = None | |
65 | return b'' | |
66 | while True: | |
67 | ret = self._cur.readline() | |
68 | if ret: | |
69 | return ret | |
70 | try: | |
71 | self._cur = six.next(self.assets) | |
72 | except StopIteration: | |
73 | self._cur = None | |
74 | return b'' | |
75 | def chunks(self, *args, **kws): | |
76 | return chunks(self, *args, **kws) | |
77 | def close(self): | |
78 | pass | |
79 | def __iter__(self): | |
80 | while True: | |
81 | line = self.readline() | |
82 | if not line: | |
83 | return | |
84 | yield line | |
85 | ||
86 | ||
87 | #------------------------------------------------------------------------------ | |
88 | class AssetGroup(object): | |
89 | # TODO: implement all expected file-like methods... | |
90 | def __init__(self, package, package_dir, regex, spec): | |
91 | # todo: remove `package_dir` -- it should be inferred... | |
92 | self.package = package | |
93 | self.pkgdir = package_dir | |
94 | self.regex = regex | |
95 | self.spec = spec | |
96 | self._fp = None | |
97 | def peek(self): | |
98 | for pkg, res in self.resources(): | |
99 | return self | |
100 | def count(self): | |
101 | return len(self) | |
102 | def exists(self): | |
103 | try: | |
104 | self.peek() | |
105 | return True | |
106 | except NoSuchAsset: | |
107 | return False | |
108 | def resources(self): | |
109 | count = 0 | |
110 | for resource in listres(self.package, self.pkgdir): | |
111 | if not self.regex.match(resource): | |
112 | continue | |
113 | count += 1 | |
114 | yield (self.package, resource) | |
115 | if count <= 0: | |
116 | raise NoSuchAsset('No asset matched "%s"' % (self.spec,)) | |
117 | def chunks(self, *args, **kws): | |
118 | return self._stream().chunks(*args, **kws) | |
119 | def __len__(self): | |
120 | return len(list(self.resources())) | |
121 | def __iter__(self): | |
122 | for pkg, res in self.resources(): | |
123 | yield Asset(self, pkg, res) | |
124 | def stream(self): | |
125 | return AssetGroupStream(self) | |
126 | def _stream(self): | |
127 | if self._fp is None: | |
128 | self._fp = self.stream() | |
129 | return self._fp | |
130 | def read(self, size=-1): | |
131 | return self._stream().read(size) | |
132 | def readline(self): | |
133 | return self._stream().readline() | |
134 | ||
135 | ||
136 | #------------------------------------------------------------------------------ | |
137 | class AssetStream(object): | |
138 | # TODO: implement all expected file-like methods... | |
139 | def __init__(self, stream, asset): | |
140 | self.stream = stream | |
141 | self.asset = asset | |
142 | def read(self, size=-1): | |
143 | return self.stream.read(size) | |
144 | def readline(self): | |
145 | return self.stream.readline() | |
146 | def close(self): | |
147 | pass | |
148 | def chunks(self, *args, **kws): | |
149 | return chunks(self.stream, *args, **kws) | |
150 | def __iter__(self): | |
151 | while True: | |
152 | line = self.readline() | |
153 | if not line: | |
154 | return | |
155 | yield line | |
156 | ||
157 | ||
158 | #------------------------------------------------------------------------------ | |
159 | class Asset(object): | |
160 | # todo: should all returned streams be "AssetStream"s that provide | |
161 | # a .asset attribute, like TransformerStream does? | |
162 | # TODO: implement all expected file-like methods... | |
163 | def __init__(self, group, package, name): | |
164 | self.group = group | |
165 | self.package = package | |
166 | self.name = name | |
167 | self._fp = None | |
168 | def __str__(self): | |
169 | return '%s:%s' % (self.package, self.name) | |
170 | def stream(self): | |
171 | return AssetStream( | |
172 | pkg_resources.resource_stream(self.package, self.name), self) | |
173 | def _stream(self): | |
174 | if self._fp is None: | |
175 | self._fp = self.stream() | |
176 | return self._fp | |
177 | def read(self, size=-1): | |
178 | return self._stream().read(size) | |
179 | def readline(self): | |
180 | return self._stream().readline() | |
181 | # compatibility with AssetGroup() API... | |
182 | def peek(self): | |
183 | if pkg_resources.resource_exists(self.package, self.name): | |
184 | return self | |
185 | raise NoSuchAsset('No asset matched "%s:%s"' % (self.package, self.name)) | |
186 | def count(self): | |
187 | return len(self) | |
188 | def exists(self): | |
189 | try: | |
190 | self.peek() | |
191 | return True | |
192 | except NoSuchAsset: | |
193 | return False | |
194 | def resources(self): | |
195 | self.peek() | |
196 | yield (self.package, self.name) | |
197 | def chunks(self, *args, **kws): | |
198 | return self._stream().chunks(*args, **kws) | |
199 | def __len__(self): | |
200 | self.peek() | |
201 | return 1 | |
202 | def __iter__(self): | |
203 | self.peek() | |
204 | yield self | |
205 | def __repr__(self): | |
206 | return '<asset "{}:{}">'.format(self.package, self.name) | |
207 | @property | |
208 | def filename(self): | |
209 | prov = pkg_resources.get_provider(self.package) | |
210 | if isinstance(prov, pkg_resources.ZipProvider): | |
211 | return None | |
212 | return pkg_resources.resource_filename(self.package, self.name) | |
213 | ||
214 | ||
215 | defaultExclude = ('.rcs', '.svn', '.git', '.hg') | |
216 | ||
217 | #------------------------------------------------------------------------------ | |
218 | def listres(pkgname, pkgdir, | |
219 | recursive=True, depthFirst=False, | |
220 | exclude=defaultExclude, showDirs=False, | |
221 | ): | |
222 | reslist = [os.path.join(pkgdir, cur) | |
223 | for cur in pkg_resources.resource_listdir(pkgname, pkgdir) | |
224 | if cur not in exclude] | |
225 | dirs = [] | |
226 | for cur in sorted(reslist): | |
227 | if pkg_resources.resource_isdir(pkgname, cur): | |
228 | if showDirs: | |
229 | yield cur + '/' | |
230 | if recursive: | |
231 | if depthFirst: | |
232 | for subcur in listres(pkgname, cur): | |
233 | yield subcur | |
234 | else: | |
235 | dirs.append(cur) | |
236 | else: | |
237 | yield cur | |
238 | for cur in dirs: | |
239 | for subcur in listres(pkgname, cur): | |
240 | yield subcur | |
241 | ||
242 | #------------------------------------------------------------------------------ | |
243 | def load(pattern, *args, **kws): | |
244 | ''' | |
245 | Given a package asset-spec glob-pattern `pattern`, returns an | |
246 | :class:`AssetGroup` object, which in turn can act as a generator of | |
247 | :class:`Asset` objects that match the pattern. | |
248 | ||
249 | Example: | |
250 | ||
251 | .. code-block:: python | |
252 | ||
253 | import asset | |
254 | ||
255 | # concatenate all 'css' files into one string: | |
256 | css = asset.load('mypackage:static/style/**.css').read() | |
257 | ||
258 | NOTE: currently, any extra parameters and keywords beyond `pattern` | |
259 | are ignored. | |
260 | ''' | |
261 | # todo: why are `args` and `kws` being ignored?... | |
262 | ||
263 | spec = pattern | |
264 | ||
265 | if ':' not in pattern: | |
266 | raise ValueError('`pattern` must be in the format "PACKAGE:GLOB"') | |
267 | ||
268 | pkgname, pkgpat = pattern.split(':', 1) | |
269 | pkgdir, pattern = globre.compile(pkgpat, split_prefix=True, flags=globre.EXACT) | |
270 | ||
271 | if pkgdir: | |
272 | idx = pkgdir.rfind('/') | |
273 | pkgdir = pkgdir[:idx] if idx >= 0 else '' | |
274 | ||
275 | group = AssetGroup(pkgname, pkgdir, pattern, spec) | |
276 | if globre.iswild(pkgpat): | |
277 | return group | |
278 | return Asset(group, pkgname, pkgpat) | |
279 | ||
280 | #------------------------------------------------------------------------------ | |
281 | def exists(pattern, *args, **kws): | |
282 | ''' | |
283 | Helper method to check to see if a `load` will be successful, | |
284 | effectively identical to:: | |
285 | ||
286 | from asset import load, NoSuchAsset | |
287 | try: | |
288 | load(pattern).peek() | |
289 | return True | |
290 | except NoSuchAsset: | |
291 | return False | |
292 | ''' | |
293 | return load(pattern, *args, **kws).exists() | |
294 | ||
295 | #------------------------------------------------------------------------------ | |
296 | def chunks(stream, size=None): | |
297 | ''' | |
298 | Returns a generator of chunks from the `stream` with a maximum | |
299 | size of `size`. I don't know why this isn't part of core Python. | |
300 | ||
301 | :Parameters: | |
302 | ||
303 | stream : file-like object | |
304 | ||
305 | The stream to fetch the chunks from. Note that the stream will | |
306 | not be repositioned in any way. | |
307 | ||
308 | size : int | 'lines'; default: null | |
309 | ||
310 | If a integer, the size of the chunks to return. If the | |
311 | string ``"lines"``, then behaves the same as `file.read()`. | |
312 | If unspecified or null, defaults to the package default | |
313 | MAXBUF size (usually 8 KiB). | |
314 | ''' | |
315 | if size == 'lines': | |
316 | for item in stream: | |
317 | # for item in stream.readline(): | |
318 | yield item | |
319 | return | |
320 | if size is None: | |
321 | size = MAXBUF | |
322 | while True: | |
323 | buf = stream.read(size) | |
324 | if not buf: | |
325 | return | |
326 | yield buf | |
327 | ||
328 | #------------------------------------------------------------------------------ | |
329 | # end of $Id$ | |
330 | # $ChangeLog$ | |
331 | #------------------------------------------------------------------------------ |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2013/09/22 | |
5 | # copy: (C) Copyright 2013-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | import pkg_resources, inspect, six | |
22 | ||
23 | from .isstr import isstr | |
24 | ||
25 | #------------------------------------------------------------------------------ | |
26 | def version(package, default=None): | |
27 | try: | |
28 | return pkg_resources.get_distribution(package).version | |
29 | except: | |
30 | return default | |
31 | ||
32 | #------------------------------------------------------------------------------ | |
33 | def symbol(spec): | |
34 | if not isstr(spec): | |
35 | return spec | |
36 | if ':' in spec: | |
37 | spec, attr = spec.split(':', 1) | |
38 | return getattr(symbol(spec), attr) | |
39 | spec = spec.split('.') | |
40 | used = spec.pop(0) | |
41 | found = __import__(used) | |
42 | for cur in spec: | |
43 | used += '.' + cur | |
44 | try: | |
45 | found = getattr(found, cur) | |
46 | except AttributeError: | |
47 | __import__(used) | |
48 | found = getattr(found, cur) | |
49 | return found | |
50 | ||
51 | #------------------------------------------------------------------------------ | |
52 | def caller(ignore=None): | |
53 | if ignore is None: | |
54 | ignore = [] | |
55 | elif isinstance(ignore, basestring): | |
56 | ignore = [ignore] | |
57 | else: | |
58 | ignore = ignore[:] | |
59 | stack = inspect.stack() | |
60 | record = None | |
61 | one = False | |
62 | try: | |
63 | for record in stack: | |
64 | if not record or not record[0]: | |
65 | continue | |
66 | mod = inspect.getmodule(record[0]) | |
67 | if not mod: | |
68 | continue | |
69 | mod = getattr(mod, '__package__', None) or getattr(mod, '__name__', None) | |
70 | if mod == 'asset' or mod.startswith('asset.'): | |
71 | continue | |
72 | if not one: | |
73 | # we've finally hit the module that actually called `caller`: | |
74 | # ignore it, since we need to return the caller's caller. | |
75 | one = True | |
76 | continue | |
77 | if mod not in ignore: | |
78 | return mod | |
79 | return None | |
80 | finally: | |
81 | del record | |
82 | del stack | |
83 | ||
84 | #------------------------------------------------------------------------------ | |
85 | # end of $Id$ | |
86 | #------------------------------------------------------------------------------ |
0 | line-3 |
0 | sub-file-line-1 |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2013/09/22 | |
5 | # copy: (C) Copyright 2013-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | import unittest | |
22 | import os.path | |
23 | import xml.etree.ElementTree as ET | |
24 | ||
25 | import pxml | |
26 | import six | |
27 | import pkg_resources | |
28 | from aadict import aadict | |
29 | ||
30 | import asset | |
31 | ||
32 | #------------------------------------------------------------------------------ | |
33 | def isEgg(pkg): | |
34 | dist = pkg_resources.get_distribution(pkg) | |
35 | return os.path.isfile(dist.location) | |
36 | ||
37 | #------------------------------------------------------------------------------ | |
38 | class TestAsset(unittest.TestCase, pxml.XmlTestMixin): | |
39 | ||
40 | maxDiff = None | |
41 | ||
42 | #---------------------------------------------------------------------------- | |
43 | def test_version(self): | |
44 | self.assertRegexpMatches(asset.version('pxml'), r'^\d+.\d+.\d+$') | |
45 | ||
46 | #---------------------------------------------------------------------------- | |
47 | def test_count(self): | |
48 | self.assertEqual(asset.load('asset:test/data/file1.nl').count(), 1) | |
49 | self.assertEqual(len(asset.load('asset:test/data/file1.nl')), 1) | |
50 | self.assertEqual(asset.load('asset:test/data/**.nl').count(), 3) | |
51 | self.assertEqual(len(asset.load('asset:test/data/**.nl')), 3) | |
52 | ||
53 | #---------------------------------------------------------------------------- | |
54 | def test_exists(self): | |
55 | self.assertEqual(asset.load('asset:test/data/file1.nl').exists(), True) | |
56 | self.assertEqual(asset.load('asset:test/data/**.nl').exists(), True) | |
57 | self.assertEqual(asset.load('asset:no-such-file.ext').exists(), False) | |
58 | ||
59 | #---------------------------------------------------------------------------- | |
60 | def test_load_multi(self): | |
61 | self.assertEqual(len(asset.load('asset:test/data/file1.nl')), 1) | |
62 | self.assertEqual( | |
63 | [str(ast) for ast in asset.load('asset:test/data/file1.nl')], | |
64 | ['asset:test/data/file1.nl']) | |
65 | self.assertEqual( | |
66 | [str(ast) for ast in asset.load('asset:test/data/**.nl')], | |
67 | ['asset:test/data/file1.nl', | |
68 | 'asset:test/data/file2.nl', | |
69 | 'asset:test/data/subdir/subfile1.nl']) | |
70 | self.assertEqual( | |
71 | [ast.read() for ast in asset.load('asset:test/data/**.nl')], | |
72 | [b'line-1\nline-2', | |
73 | b'line-3\n', | |
74 | b'sub-file-line-1\n']) | |
75 | ||
76 | #---------------------------------------------------------------------------- | |
77 | def test_load_single(self): | |
78 | loaded = [] | |
79 | for item in asset.load('asset:test/data/file1.nl'): | |
80 | loaded.append(item) | |
81 | self.assertEqual(len(loaded), 1) | |
82 | self.assertEqual(loaded[0].package, 'asset') | |
83 | self.assertEqual(loaded[0].name, 'test/data/file1.nl') | |
84 | with self.assertRaises(asset.NoSuchAsset) as cm: | |
85 | asset.load('asset:no-such-file.ext').peek() | |
86 | ||
87 | #---------------------------------------------------------------------------- | |
88 | def test_load_group_read(self): | |
89 | self.assertEqual( | |
90 | asset.load('asset:test/data/file1.nl').read(), b'line-1\nline-2') | |
91 | self.assertEqual( | |
92 | asset.load('asset:test/data/file2.nl').read(), b'line-3\n') | |
93 | self.assertEqual( | |
94 | asset.load('asset:test/data/*.nl').read(), b'line-1\nline-2line-3\n') | |
95 | ag = asset.load('asset:test/data/*.nl') | |
96 | self.assertEqual(ag.readline(), b'line-1\n') | |
97 | self.assertEqual(ag.readline(), b'line-2') | |
98 | self.assertEqual(ag.readline(), b'line-3\n') | |
99 | ||
100 | #---------------------------------------------------------------------------- | |
101 | def test_load_example(self): | |
102 | out = ET.Element('nodes') | |
103 | for item in asset.load('asset:test/data/**.nl'): | |
104 | cur = ET.SubElement(out, 'node', name=item.name) | |
105 | cur.text = item.read().decode() | |
106 | out = ET.tostring(out) | |
107 | chk = b'''\ | |
108 | <nodes> | |
109 | <node name="test/data/file1.nl">line-1 | |
110 | line-2</node> | |
111 | <node name="test/data/file2.nl">line-3 | |
112 | </node> | |
113 | <node name="test/data/subdir/subfile1.nl">sub-file-line-1 | |
114 | </node> | |
115 | </nodes> | |
116 | ''' | |
117 | self.assertXmlEqual(out, chk) | |
118 | ||
119 | #---------------------------------------------------------------------------- | |
120 | def test_listres(self): | |
121 | self.assertEqual( | |
122 | list(asset.listres('asset', 'test/data', showDirs=True)), | |
123 | [ | |
124 | 'test/data/file1.nl', | |
125 | 'test/data/file2.nl', | |
126 | 'test/data/subdir/', | |
127 | 'test/data/subdir/subfile1.nl', | |
128 | ]) | |
129 | ||
130 | #---------------------------------------------------------------------------- | |
131 | def test_filename_egg(self): | |
132 | # NOTE: this requires that `pxml` be installed as a zipped egg, i.e.: | |
133 | # easy_install --zip-ok pxml | |
134 | if not isEgg('pxml'): | |
135 | raise unittest.SkipTest('package "pxml" must be installed as a zipped egg') | |
136 | for item in asset.load('pxml:__init__.py'): | |
137 | self.assertIsNone(item.filename) | |
138 | ||
139 | #---------------------------------------------------------------------------- | |
140 | def test_filename_noegg(self): | |
141 | # NOTE: this requires that `globre` be installed as an UNzipped pkg, i.e.: | |
142 | # easy_install --always-unzip globre | |
143 | if isEgg('globre'): | |
144 | raise unittest.SkipTest('package "globre" must not be installed as a zipped egg') | |
145 | for item in asset.load('globre:__init__.py'): | |
146 | self.assertIsNotNone(item.filename) | |
147 | ||
148 | #---------------------------------------------------------------------------- | |
149 | def test_readWithSize(self): | |
150 | self.assertEqual( | |
151 | asset.load('asset:test/data/file**').stream().read(), | |
152 | b'line-1\nline-2line-3\n') | |
153 | self.assertEqual( | |
154 | asset.load('asset:test/data/file**').stream().read(1024), | |
155 | b'line-1\nline-2line-3\n') | |
156 | stream = asset.load('asset:test/data/file**').stream() | |
157 | self.assertEqual(stream.read(5), b'line-') | |
158 | self.assertEqual(stream.read(5), b'1\nlin') | |
159 | self.assertEqual(stream.read(5), b'e-2li') | |
160 | self.assertEqual(stream.read(3), b'ne-') | |
161 | self.assertEqual(stream.read(3), b'3\n') | |
162 | self.assertEqual(stream.read(3), b'') | |
163 | ||
164 | #---------------------------------------------------------------------------- | |
165 | def test_streamIteration(self): | |
166 | stream = asset.load('asset:test/data/file**').stream() | |
167 | self.assertEqual(stream.readline(), b'line-1\n') | |
168 | self.assertEqual(stream.readline(), b'line-2') | |
169 | self.assertEqual(stream.readline(), b'line-3\n') | |
170 | self.assertEqual(stream.readline(), b'') | |
171 | stream = asset.load('asset:test/data/file**').stream() | |
172 | chk = list(reversed([ | |
173 | b'line-1\n', | |
174 | b'line-2', | |
175 | b'line-3\n', | |
176 | ])) | |
177 | for line in stream: | |
178 | self.assertEqual(line, chk.pop()) | |
179 | ||
180 | #---------------------------------------------------------------------------- | |
181 | def test_csv(self): | |
182 | import csv | |
183 | lines = [line.decode() for line in asset.load('asset:test/data.csv').stream()] | |
184 | reader = csv.reader(lines) | |
185 | self.assertEqual(six.next(reader), ['a', 'b', 'c']) | |
186 | self.assertEqual(six.next(reader), ['1', '2', '3']) | |
187 | with self.assertRaises(StopIteration): | |
188 | six.next(reader) | |
189 | ||
190 | #---------------------------------------------------------------------------- | |
191 | def test_chunks_bytes(self): | |
192 | src = six.BytesIO('foo-1\nbar\nzig') | |
193 | self.assertEqual( | |
194 | list(asset.chunks(src, 3)), | |
195 | ['foo', '-1\n', 'bar', '\nzi', 'g']) | |
196 | self.assertEqual( | |
197 | list(asset.chunks(asset.load('asset:test/data/file1.nl').stream(), 3)), | |
198 | ['lin', 'e-1', '\nli', 'ne-', '2']) | |
199 | self.assertEqual( | |
200 | list(asset.chunks(asset.load('asset:test/data/file**').stream(), 3)), | |
201 | ['lin', 'e-1', '\nli', 'ne-', '2li', 'ne-', '3\n']) | |
202 | self.assertEqual( | |
203 | list(asset.load('asset:test/data/file1.nl').chunks(3)), | |
204 | ['lin', 'e-1', '\nli', 'ne-', '2']) | |
205 | self.assertEqual( | |
206 | list(asset.load('asset:test/data/file**').chunks(3)), | |
207 | ['lin', 'e-1', '\nli', 'ne-', '2li', 'ne-', '3\n']) | |
208 | ||
209 | #---------------------------------------------------------------------------- | |
210 | def test_chunks_lines(self): | |
211 | src = six.BytesIO('foo-1\nbar\nzig') | |
212 | self.assertEqual( | |
213 | list(asset.chunks(src, 'lines')), | |
214 | ['foo-1\n', 'bar\n', 'zig']) | |
215 | self.assertEqual( | |
216 | list(asset.chunks(asset.load('asset:test/data/file1.nl').stream(), 'lines')), | |
217 | ['line-1\n', 'line-2']) | |
218 | self.assertEqual( | |
219 | list(asset.chunks(asset.load('asset:test/data/file**').stream(), 'lines')), | |
220 | ['line-1\n', 'line-2', 'line-3\n']) | |
221 | self.assertEqual( | |
222 | list(asset.load('asset:test/data/file1.nl').chunks('lines')), | |
223 | ['line-1\n', 'line-2']) | |
224 | self.assertEqual( | |
225 | list(asset.load('asset:test/data/file**').chunks('lines')), | |
226 | ['line-1\n', 'line-2', 'line-3\n']) | |
227 | ||
228 | ||
229 | #------------------------------------------------------------------------------ | |
230 | # end of $Id$ | |
231 | # $ChangeLog$ | |
232 | #------------------------------------------------------------------------------ |
0 | # -*- coding: utf-8 -*- | |
1 | #------------------------------------------------------------------------------ | |
2 | # file: $Id$ | |
3 | # auth: metagriffin <[email protected]> | |
4 | # date: 2016/01/03 | |
5 | # copy: (C) Copyright 2016-EOT metagriffin -- see LICENSE.txt | |
6 | #------------------------------------------------------------------------------ | |
7 | # This software is free software: you can redistribute it and/or | |
8 | # modify it under the terms of the GNU General Public License as | |
9 | # published by the Free Software Foundation, either version 3 of the | |
10 | # License, or (at your option) any later version. | |
11 | # | |
12 | # This software is distributed in the hope that it will be useful, but | |
13 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | # General Public License for more details. | |
16 | # | |
17 | # You should have received a copy of the GNU General Public License | |
18 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
19 | #------------------------------------------------------------------------------ | |
20 | ||
21 | import unittest | |
22 | ||
23 | from aadict import aadict | |
24 | ||
25 | import asset | |
26 | ||
27 | #------------------------------------------------------------------------------ | |
28 | class TestPlugins(unittest.TestCase): | |
29 | ||
30 | maxDiff = None | |
31 | ||
32 | @staticmethod | |
33 | @asset.plugin('test-group', 'test-name') | |
34 | def method(): pass | |
35 | ||
36 | #---------------------------------------------------------------------------- | |
37 | def test_plugin_sorting_intra(self): | |
38 | from .plugin import _sort_plugins | |
39 | self.assertEqual( | |
40 | list(_sort_plugins('myext', [ | |
41 | aadict(name='foo', after=None, before=None, order=8, replace=False, final=True), | |
42 | aadict(name='foo', after=None, before=None, order=2, replace=False, final=False), | |
43 | aadict(name='foo', after=None, before=None, order=9, replace=False, final=False), | |
44 | aadict(name='foo', after=None, before=None, order=5, replace=True, final=False), | |
45 | ])), [ | |
46 | aadict(name='foo', after=None, before=None, order=5, replace=True, final=False), | |
47 | aadict(name='foo', after=None, before=None, order=8, replace=False, final=True), | |
48 | ]) | |
49 | ||
50 | #---------------------------------------------------------------------------- | |
51 | def test_plugin_sorting_inter(self): | |
52 | from .plugin import _sort_plugins | |
53 | self.assertEqual( | |
54 | list(_sort_plugins('myext', [ | |
55 | aadict(name='a', after=None, before=None, order=8, replace=False, final=False), | |
56 | aadict(name='b', after=None, before=None, order=9, replace=False, final=False), | |
57 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
58 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
59 | aadict(name='c', after=None, before='a', order=0, replace=False, final=False), | |
60 | ])), [ | |
61 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
62 | aadict(name='c', after=None, before='a', order=0, replace=False, final=False), | |
63 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
64 | ]) | |
65 | ||
66 | #---------------------------------------------------------------------------- | |
67 | def test_plugin_sorting_spec_valid(self): | |
68 | from .plugin import _sort_plugins | |
69 | self.assertEqual( | |
70 | list(_sort_plugins('myext', [ | |
71 | aadict(name='a', after=None, before=None, order=8, replace=False, final=False), | |
72 | aadict(name='b', after=None, before=None, order=9, replace=False, final=False), | |
73 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
74 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
75 | aadict(name='c', after=None, before='a', order=0, replace=False, final=False), | |
76 | ], 'c,b,a')), [ | |
77 | aadict(name='c', after=None, before='a', order=0, replace=False, final=False), | |
78 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
79 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
80 | ]) | |
81 | self.assertEqual( | |
82 | list(_sort_plugins('myext', [ | |
83 | aadict(name='a', after=None, before=None, order=8, replace=False, final=False), | |
84 | aadict(name='b', after=None, before=None, order=9, replace=False, final=False), | |
85 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
86 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
87 | aadict(name='c', after=None, before='a', order=0, replace=False, final=False), | |
88 | ], '-c')), [ | |
89 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
90 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
91 | ]) | |
92 | ||
93 | #---------------------------------------------------------------------------- | |
94 | def test_plugin_sorting_spec_invalid(self): | |
95 | from .plugin import _sort_plugins | |
96 | with self.assertRaises(TypeError) as cm: | |
97 | list(_sort_plugins('myext', [ | |
98 | aadict(name='a', after=None, before=None, order=8, replace=False, final=False), | |
99 | aadict(name='b', after=None, before=None, order=9, replace=False, final=False), | |
100 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
101 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
102 | aadict(name='c', after=None, before='a', order=0, replace=False, final=False), | |
103 | ], '-c,-b')) | |
104 | self.assertEqual( | |
105 | str(cm.exception), | |
106 | "myext plugin type 'a' specified unavailable 'after' dependency 'b'") | |
107 | ||
108 | #---------------------------------------------------------------------------- | |
109 | def test_plugin_sorting_unavailable(self): | |
110 | from .plugin import _sort_plugins | |
111 | with self.assertRaises(TypeError) as cm: | |
112 | list(_sort_plugins('myext', [ | |
113 | aadict(name='bar', after='foo', before=None, order=0, replace=False, final=False), | |
114 | ])) | |
115 | self.assertEqual( | |
116 | str(cm.exception), | |
117 | "myext plugin type 'bar' specified unavailable 'after' dependency 'foo'") | |
118 | with self.assertRaises(TypeError) as cm: | |
119 | list(_sort_plugins('myext', [ | |
120 | aadict(name='bar', after=None, before='foo', order=0, replace=False, final=False), | |
121 | ])) | |
122 | self.assertEqual( | |
123 | str(cm.exception), | |
124 | "myext plugin type 'bar' specified unavailable 'before' dependency 'foo'") | |
125 | with self.assertRaises(TypeError) as cm: | |
126 | list(_sort_plugins('myext', [ | |
127 | aadict(name='foo', after=None, before='bar', order=0, replace=False, final=False), | |
128 | aadict(name='bar', after=None, before='foo', order=0, replace=False, final=False), | |
129 | ])) | |
130 | self.assertEqual( | |
131 | str(cm.exception), | |
132 | "myext has cyclical dependencies in plugins ['bar', 'foo']") | |
133 | ||
134 | #---------------------------------------------------------------------------- | |
135 | def test_plugin_spec_valid(self): | |
136 | import re | |
137 | from .plugin import _parse_spec | |
138 | self.assertEqual(_parse_spec(None), ()) | |
139 | self.assertEqual(_parse_spec('*'), ()) | |
140 | self.assertEqual(_parse_spec('-foo,+bar'), (aadict(op='-', target='foo'), aadict(op='+', target='bar'))) | |
141 | self.assertEqual(_parse_spec('-foo,-bar'), (aadict(op='-', target='foo'), aadict(op='-', target='bar'))) | |
142 | self.assertEqual(_parse_spec(' - foo, - bar'), (aadict(op='-', target='foo'), aadict(op='-', target='bar'))) | |
143 | self.assertEqual(_parse_spec(' - foo - bar '), (aadict(op='-', target='foo'), aadict(op='-', target='bar'))) | |
144 | self.assertEqual(_parse_spec('foo,?bar'), (aadict(op=' ', target='foo'), aadict(op='?', target='bar'))) | |
145 | self.assertEqual(_parse_spec('foo,?bar'), (aadict(op=' ', target='foo'), aadict(op='?', target='bar'))) | |
146 | self.assertEqual( | |
147 | _parse_spec('/(foo|bar)/'), | |
148 | (aadict(op='/', target=re.compile('(foo|bar)')),)) | |
149 | self.assertEqual( | |
150 | _parse_spec('+zig,/(foo|bar)/'), | |
151 | (aadict(op='+', target='zig'), aadict(op='/', target=re.compile('(foo|bar)')))) | |
152 | self.assertEqual( | |
153 | _parse_spec('/zig,/(foo|bar)/'), | |
154 | (aadict(op='/', target=re.compile('zig,/(foo|bar)')),)) | |
155 | ||
156 | #---------------------------------------------------------------------------- | |
157 | def test_plugin_spec_invalid(self): | |
158 | from .plugin import _parse_spec | |
159 | with self.assertRaises(ValueError) as cm: | |
160 | _parse_spec('foo,-bar') | |
161 | self.assertEqual( | |
162 | str(cm.exception), | |
163 | "invalid mixing of relative (['-']) and absolute ([' ']) prefixes in plugin specification") | |
164 | with self.assertRaises(ValueError) as cm: | |
165 | _parse_spec('-foo,bar') | |
166 | self.assertEqual( | |
167 | str(cm.exception), | |
168 | "invalid mixing of relative (['-']) and absolute ([' ']) prefixes in plugin specification") | |
169 | with self.assertRaises(ValueError) as cm: | |
170 | _parse_spec('-foo,?bar') | |
171 | self.assertEqual( | |
172 | str(cm.exception), | |
173 | "invalid mixing of relative (['-']) and absolute (['?']) prefixes in plugin specification") | |
174 | with self.assertRaises(ValueError) as cm: | |
175 | _parse_spec('/foo') | |
176 | self.assertEqual( | |
177 | str(cm.exception), | |
178 | 'regex plugin loading expression must start and end with "/"') | |
179 | ||
180 | #---------------------------------------------------------------------------- | |
181 | def test_plugin_spec_match(self): | |
182 | from .plugin import _parse_spec, _match_spec | |
183 | self.assertTrue(_match_spec(_parse_spec('*'), 'foo')) | |
184 | self.assertTrue(_match_spec(_parse_spec('/foo/'), 'foo')) | |
185 | self.assertFalse(_match_spec(_parse_spec('/foo/'), 'bar')) | |
186 | self.assertTrue(_match_spec(_parse_spec('/(foo|bar)/'), 'foo')) | |
187 | self.assertTrue(_match_spec(_parse_spec('/(foo|bar)/'), 'bar')) | |
188 | self.assertTrue(_match_spec(_parse_spec('foo,?bar'), 'foo')) | |
189 | self.assertTrue(_match_spec(_parse_spec('foo,?bar'), 'bar')) | |
190 | self.assertTrue(_match_spec(_parse_spec('-foo'), 'bar')) | |
191 | self.assertFalse(_match_spec(_parse_spec('-foo'), 'foo')) | |
192 | self.assertFalse(_match_spec(_parse_spec('foo,?bar'), 'zog')) | |
193 | self.assertTrue(_match_spec(_parse_spec('+foo'), 'foo')) | |
194 | self.assertTrue(_match_spec(_parse_spec('+foo'), 'bar')) | |
195 | ||
196 | #---------------------------------------------------------------------------- | |
197 | def test_plugin_asset_load(self): | |
198 | from .plugin import plugins, _load_asset_plugin | |
199 | self.assertEqual( | |
200 | _load_asset_plugin(aadict(target='asset.test_plugin.TestPlugins.method')).handle, | |
201 | self.method) | |
202 | plugs = list(plugins('test-group', 'asset.test_plugin.TestPlugins.method')) | |
203 | self.assertEqual( | |
204 | [plin.handle for plin in plugs], | |
205 | [self.method]) | |
206 | with self.assertRaises(ValueError) as cm: | |
207 | list(plugins('test-group', 'asset.test_plugin.TestPlugins.no_such_method')) | |
208 | self.assertEqual( | |
209 | str(cm.exception), | |
210 | "could not load plugin 'asset.test_plugin.TestPlugins.no_such_method'") | |
211 | ||
212 | #---------------------------------------------------------------------------- | |
213 | def test_plugin_asset_mixed(self): | |
214 | from .plugin import _sort_plugins | |
215 | self.assertEqual( | |
216 | list(_sort_plugins('myext', [ | |
217 | aadict(name='a', after=None, before=None, order=8, replace=False, final=False), | |
218 | aadict(name='b', after=None, before=None, order=9, replace=False, final=False), | |
219 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
220 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
221 | aadict(name='c', after=None, before='b', order=0, replace=False, final=False), | |
222 | aadict(name='d.e', after='b', before='a', order=0, replace=False, final=False), | |
223 | ], '+d.e')), [ | |
224 | aadict(name='c', after=None, before='b', order=0, replace=False, final=False), | |
225 | aadict(name='b', after=None, before=None, order=2, replace=False, final=True), | |
226 | aadict(name='d.e', after='b', before='a', order=0, replace=False, final=False), | |
227 | aadict(name='a', after='b', before=None, order=5, replace=False, final=True), | |
228 | ]) | |
229 | ||
230 | #---------------------------------------------------------------------------- | |
231 | def test_plugin_decorator(self): | |
232 | from .plugin import plugin | |
233 | @plugin('asset.example', 'foo', before='bar') | |
234 | def my_foo_plugin(): pass | |
235 | @plugin('asset.example', 'bar', after='foo', order=3, replace=True, final=True) | |
236 | def my_bar_plugin(): pass | |
237 | self.assertEqual(my_foo_plugin.plugin_group, 'asset.example') | |
238 | self.assertEqual(my_foo_plugin.plugin_name, 'foo') | |
239 | self.assertEqual(my_foo_plugin.before, 'bar') | |
240 | self.assertFalse(hasattr(my_foo_plugin, 'after')) | |
241 | self.assertFalse(hasattr(my_foo_plugin, 'order')) | |
242 | self.assertFalse(hasattr(my_foo_plugin, 'replace')) | |
243 | self.assertFalse(hasattr(my_foo_plugin, 'final')) | |
244 | self.assertEqual(my_bar_plugin.plugin_group, 'asset.example') | |
245 | self.assertEqual(my_bar_plugin.plugin_name, 'bar') | |
246 | self.assertEqual(my_bar_plugin.after, 'foo') | |
247 | self.assertFalse(hasattr(my_bar_plugin, 'before')) | |
248 | self.assertEqual(my_bar_plugin.order, 3) | |
249 | self.assertEqual(my_bar_plugin.replace, True) | |
250 | self.assertEqual(my_bar_plugin.final, True) | |
251 | ||
252 | #---------------------------------------------------------------------------- | |
253 | def test_plugin_can_declare_name(self): | |
254 | pset = asset.plugins( | |
255 | 'test-group', 'asset.test_plugin.TestPlugins.method') | |
256 | self.assertEqual(pset.plugins[0].name, 'test-name') | |
257 | ||
258 | #------------------------------------------------------------------------------ | |
259 | class TestPluginSet(unittest.TestCase): | |
260 | ||
261 | maxDiff = None | |
262 | ||
263 | @staticmethod | |
264 | def increment(value, counter=None, **kw): | |
265 | if counter: | |
266 | counter() | |
267 | if 'abort' in kw and value == kw['abort']: | |
268 | return None | |
269 | if value is None: | |
270 | return None | |
271 | return value + 1 | |
272 | ||
273 | @staticmethod | |
274 | @asset.plugin('test-group', 'decrement') | |
275 | def decrement(value): | |
276 | return value - 1 | |
277 | ||
278 | #---------------------------------------------------------------------------- | |
279 | def test_filter_empty(self): | |
280 | self.assertEqual( | |
281 | 'foo', | |
282 | asset.PluginSet('group', None, []).filter('foo')) | |
283 | ||
284 | #---------------------------------------------------------------------------- | |
285 | def test_handle_empty(self): | |
286 | with self.assertRaises(ValueError) as cm: | |
287 | asset.PluginSet('group', None, []).handle('foo') | |
288 | self.assertEqual( | |
289 | str(cm.exception), "No plugins available in group 'group'") | |
290 | ||
291 | #---------------------------------------------------------------------------- | |
292 | def test_filter_aborts(self): | |
293 | count = dict(value=0) | |
294 | def counter(): | |
295 | count['value'] = count['value'] + 1 | |
296 | pset = asset.plugins( | |
297 | 'test-group', ','.join(['asset.test_plugin.TestPluginSet.increment'] * 5)) | |
298 | self.assertEqual(pset.filter(0, abort=2, counter=counter), None) | |
299 | self.assertEqual(count['value'], 3) | |
300 | ||
301 | #---------------------------------------------------------------------------- | |
302 | def test_handle_perseveres(self): | |
303 | count = dict(value=0) | |
304 | def counter(): | |
305 | count['value'] = count['value'] + 1 | |
306 | pset = asset.plugins( | |
307 | 'test-group', ','.join(['asset.test_plugin.TestPluginSet.increment'] * 5)) | |
308 | self.assertEqual(pset.handle(0, abort=2, counter=counter), None) | |
309 | self.assertEqual(count['value'], 5) | |
310 | ||
311 | #---------------------------------------------------------------------------- | |
312 | def test_select(self): | |
313 | pset = asset.plugins( | |
314 | 'test-group', ','.join([ | |
315 | 'asset.test_plugin.TestPluginSet.increment', | |
316 | 'asset.test_plugin.TestPluginSet.decrement'])) | |
317 | pset2 = pset.select('decrement') | |
318 | self.assertEqual( | |
319 | [p.handle for p in pset.plugins], [self.increment, self.decrement]) | |
320 | self.assertEqual( | |
321 | [p.handle for p in pset2.plugins], [self.decrement]) | |
322 | ||
323 | #---------------------------------------------------------------------------- | |
324 | def test_repr(self): | |
325 | self.assertEqual( | |
326 | repr(asset.plugins( | |
327 | 'test-group', 'asset.test_plugin.TestPluginSet.decrement')), | |
328 | "<PluginSet group='test-group' plugins=['decrement']>") | |
329 | ||
330 | ||
331 | #------------------------------------------------------------------------------ | |
332 | # end of $Id$ | |
333 | # $ChangeLog$ | |
334 | #------------------------------------------------------------------------------ |
0 | Metadata-Version: 1.1 | |
1 | Name: asset | |
2 | Version: 0.6.13 | |
3 | Summary: A package resource and symbol loading helper library. | |
4 | Home-page: http://github.com/metagriffin/asset | |
5 | Author: metagriffin | |
6 | Author-email: [email protected] | |
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 | Keywords: python package pkg_resources asset resolve lookup loader | |
190 | Platform: any | |
191 | Classifier: Development Status :: 5 - Production/Stable | |
192 | Classifier: Intended Audience :: Developers | |
193 | Classifier: Programming Language :: Python | |
194 | Classifier: Operating System :: OS Independent | |
195 | Classifier: Natural Language :: English | |
196 | Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+) |
0 | CHANGELOG.rst | |
1 | LICENSE.txt | |
2 | MANIFEST.in | |
3 | README.rst | |
4 | TODO.txt | |
5 | VERSION.txt | |
6 | setup.cfg | |
7 | setup.py | |
8 | test-requirements.txt | |
9 | asset/__init__.py | |
10 | asset/isstr.py | |
11 | asset/plugin.py | |
12 | asset/resource.py | |
13 | asset/symbol.py | |
14 | asset/test.py | |
15 | asset/test_plugin.py | |
16 | asset.egg-info/PKG-INFO | |
17 | asset.egg-info/SOURCES.txt | |
18 | asset.egg-info/dependency_links.txt | |
19 | asset.egg-info/requires.txt | |
20 | asset.egg-info/top_level.txt | |
21 | asset.egg-info/zip-safe | |
22 | asset/test/data.csv | |
23 | asset/test/data/file1.nl | |
24 | asset/test/data/file2.nl | |
25 | asset/test/data/subdir/subfile1.nl⏎ |
0 | asset |
0 | [easy_install] | |
1 | zip_ok = true | |
2 | ||
3 | [nosetests] | |
4 | match = ^test | |
5 | nocapture = 1 | |
6 | cover-branches = 1 | |
7 | cover-package = asset | |
8 | cover-erase = 1 | |
9 | ||
10 | [register] | |
11 | repository = pypi-metagriffin | |
12 | ||
13 | [upload] | |
14 | repository = pypi-metagriffin | |
15 | ||
16 | [egg_info] | |
17 | tag_build = | |
18 | tag_date = 0 | |
19 |
0 | #!/usr/bin/env python | |
1 | # -*- coding: utf-8 -*- | |
2 | #------------------------------------------------------------------------------ | |
3 | # file: $Id$ | |
4 | # auth: metagriffin <[email protected]> | |
5 | # date: 2013/10/29 | |
6 | # copy: (C) Copyright 2013-EOT metagriffin -- see LICENSE.txt | |
7 | #------------------------------------------------------------------------------ | |
8 | # This software is free software: you can redistribute it and/or | |
9 | # modify it under the terms of the GNU General Public License as | |
10 | # published by the Free Software Foundation, either version 3 of the | |
11 | # License, or (at your option) any later version. | |
12 | # | |
13 | # This software is distributed in the hope that it will be useful, but | |
14 | # WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
16 | # General Public License for more details. | |
17 | # | |
18 | # You should have received a copy of the GNU General Public License | |
19 | # along with this program. If not, see http://www.gnu.org/licenses/. | |
20 | #------------------------------------------------------------------------------ | |
21 | ||
22 | import os, sys, setuptools | |
23 | from setuptools import setup, find_packages | |
24 | ||
25 | # require python 2.7+ | |
26 | if sys.hexversion < 0x02070000: | |
27 | raise RuntimeError('This package requires python 2.7 or better') | |
28 | ||
29 | heredir = os.path.abspath(os.path.dirname(__file__)) | |
30 | def read(*parts, **kw): | |
31 | try: return open(os.path.join(heredir, *parts)).read() | |
32 | except: return kw.get('default', '') | |
33 | ||
34 | test_dependencies = [ | |
35 | 'nose >= 1.3.0', | |
36 | 'coverage >= 3.5.3', | |
37 | # note: `pxml` should be installed as an egg, i.e.: | |
38 | # easy_install --zip-ok pxml | |
39 | # for the unit tests to be able to test that. | |
40 | 'pxml >= 0.2.13', | |
41 | ] | |
42 | ||
43 | dependencies = [ | |
44 | # note: `globre` should be installed unzipped, i.e.: | |
45 | # easy_install --always-unzip globre | |
46 | # for the unit tests to be able to test that. | |
47 | 'globre >= 0.1.5', | |
48 | 'six >= 1.10.0', | |
49 | 'aadict >= 0.2.2', | |
50 | ] | |
51 | ||
52 | entrypoints = None | |
53 | ||
54 | classifiers = [ | |
55 | 'Development Status :: 5 - Production/Stable', | |
56 | 'Intended Audience :: Developers', | |
57 | 'Programming Language :: Python', | |
58 | 'Operating System :: OS Independent', | |
59 | 'Natural Language :: English', | |
60 | 'License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)', | |
61 | ] | |
62 | ||
63 | setup( | |
64 | name = 'asset', | |
65 | version = read('VERSION.txt', default='0.0.1').strip(), | |
66 | description = 'A package resource and symbol loading helper library.', | |
67 | long_description = read('README.rst'), | |
68 | classifiers = classifiers, | |
69 | author = 'metagriffin', | |
70 | author_email = '[email protected]', | |
71 | url = 'http://github.com/metagriffin/asset', | |
72 | keywords = 'python package pkg_resources asset resolve lookup loader', | |
73 | packages = find_packages(), | |
74 | platforms = ['any'], | |
75 | include_package_data = True, | |
76 | zip_safe = True, | |
77 | install_requires = dependencies, | |
78 | tests_require = test_dependencies, | |
79 | test_suite = 'asset', | |
80 | entry_points = entrypoints, | |
81 | license = 'GPLv3+', | |
82 | ) | |
83 | ||
84 | #------------------------------------------------------------------------------ | |
85 | # end of $Id$ | |
86 | #------------------------------------------------------------------------------ |