guacamole-0.9.2/0000775000175000017500000000000012560714745013442 5ustar zygazyga00000000000000guacamole-0.9.2/COPYING0000664000175000017500000010451212522110401014451 0ustar zygazyga00000000000000 GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The GNU General Public License is a free, copyleft license for software and other kinds of works. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS 0. Definitions. "This License" refers to version 3 of the GNU General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a) The work must carry prominent notices stating that you modified it, and giving a relevant date. b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d) Limiting the use for publicity purposes of names of licensors or authors of the material; or e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation. Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice. Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: Copyright (C) This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see . The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read .guacamole-0.9.2/PKG-INFO0000664000175000017500000001106512560714745014542 0ustar zygazyga00000000000000Metadata-Version: 1.1 Name: guacamole Version: 0.9.2 Summary: Guacamole is an command line tool library for Python Home-page: https://github.com/zyga/guacamole Author: Zygmunt Krynicki Author-email: me@zygoon.pl License: LGPLv3 Description: ============================================================ Guacamole - Framework for Creating Command Line Applications ============================================================ .. image:: https://badge.fury.io/py/guacamole.png :target: http://badge.fury.io/py/guacamole .. image:: https://travis-ci.org/zyga/guacamole.png?branch=master :target: https://travis-ci.org/zyga/guacamole .. image:: https://pypip.in/d/guacamole/badge.png :target: https://pypi.python.org/pypi/guacamole Tools, done right ================= Guacamole is a LGPLv3 licensed toolkit for creating good command line applications. Guacamole that does the right things for you and makes writing applications easier. .. testsetup:: import guacamole .. doctest:: >>> class HelloWorld(guacamole.Command): ... """A simple hello-world application.""" ... def register_arguments(self, parser): ... parser.add_argument('name') ... def invoked(self, ctx): ... print("Hello {0}!".format(ctx.args.name)) Running it directly is as simple as calling ``main()``: .. doctest:: >>> HelloWorld().main(['Guacamole'], exit=False) Hello Guacamole! 0 What you didn't have to do is what matters: - configure the argument parser - define and setup application logging - initialize internationalization features - add debugging facilities - write a custom crash handler Features ======== * Free software: LGPLv3 license * Documentation: https://guacamole.readthedocs.org. * Create command classes and run them from command line. * Group commands to create complex tools. * Use recipes, ingredients and spices to customize behavior History ======= 0.9.2 (2015-08-06) ------------------ * Fix https://github.com/zyga/guacamole/issues/11 0.9.1 (2015-08-06) ------------------ * Fix https://github.com/zyga/guacamole/issues/9 0.9 (2015-05-11) ---------------- * Vastly improved documentation * Bugfixes and changes based on early feedback * New cmdtree module with two ingredients (for instantiating commands and for dispatching the invoked method) * Simplified argparse ingredient (for just handling parser) * Unit tests and doctests for some of the functionality 0.8 (2015-04-21) ---------------- * First release on PyPI. 2012-2015 --------- * Released on PyPI as a part of plainbox as ``plainbox.impl.clitools``, ``plainbox.impl.logging``, ``plainbox.i18n`` and ``plainbox.impl.secure.plugins``. Keywords: argparse cli tool command sub-command subcommand Platform: UNKNOWN Classifier: Development Status :: 3 - Alpha Classifier: Intended Audience :: Developers Classifier: Environment :: Console Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3) Classifier: Natural Language :: English Classifier: Natural Language :: Polish Classifier: Operating System :: MacOS :: MacOS X Classifier: Operating System :: Microsoft :: Windows :: Windows 7 Classifier: Operating System :: Microsoft :: Windows :: Windows XP Classifier: Operating System :: POSIX Classifier: Operating System :: POSIX :: Linux Classifier: Topic :: Software Development Classifier: Topic :: Software Development :: Libraries Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy guacamole-0.9.2/COPYING.LESSER0000664000175000017500000001674212522110401015454 0ustar zygazyga00000000000000 GNU LESSER GENERAL PUBLIC LICENSE Version 3, 29 June 2007 Copyright (C) 2007 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below. 0. Additional Definitions. As used herein, "this License" refers to version 3 of the GNU Lesser General Public License, and the "GNU GPL" refers to version 3 of the GNU General Public License. "The Library" refers to a covered work governed by this License, other than an Application or a Combined Work as defined below. An "Application" is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library. A "Combined Work" is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the "Linked Version". The "Minimal Corresponding Source" for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version. The "Corresponding Application Code" for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work. 1. Exception to Section 3 of the GNU GPL. You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL. 2. Conveying Modified Versions. If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version: a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy. 3. Object Code Incorporating Material from Library Header Files. The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following: a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the object code with a copy of the GNU GPL and this license document. 4. Combined Works. You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following: a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License. b) Accompany the Combined Work with a copy of the GNU GPL and this license document. c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document. d) Do one of the following: 0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source. 1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version. e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.) 5. Combined Libraries. You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following: a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License. b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work. 6. Revised Versions of the GNU Lesser General Public License. The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation. If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.guacamole-0.9.2/examples/0000775000175000017500000000000012560714745015260 5ustar zygazyga00000000000000guacamole-0.9.2/examples/adder.py0000775000175000017500000000552612522110401016675 0ustar zygazyga00000000000000#!/usr/bin/env python # encoding: utf-8 # # Copyright (c) 2015, Canonical Ltd. # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # 3. Neither the name of the copyright holder nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. """A trivial program that adds two numbers with Guacamole.""" from __future__ import absolute_import, print_function, unicode_literals from guacamole import Command class Addder(Command): """Add two numbers together.""" def register_arguments(self, parser): """ Guacamole method used by the argparse ingredient. :param parser: Argument parser (from :mod:`argparse`) specific to this command. """ parser.add_argument('x', type=int, help='the first value') parser.add_argument('y', type=int, help='the second value') def invoked(self, ctx): """ Guacamole method used by the command ingredient. :param ctx: The guacamole context object. Context provides access to all features of guacamole. The argparse ingredient adds the ``args`` attribute to it. That attribute contains the result of parsing command line arguments. :returns: The return code of the command. Guacamole translates ``None`` to a successful exit status (return code zero). """ print("{} + {} = {}".format( ctx.args.x, ctx.args.y, ctx.args.x + ctx.args.y)) if __name__ == '__main__': Addder().main() guacamole-0.9.2/examples/rainbow.py0000775000175000017500000001774412553154621017304 0ustar zygazyga00000000000000#!/usr/bin/env python # encoding: utf-8 # # Copyright (c) 2015, Canonical Ltd. # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # 3. Neither the name of the copyright holder nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. """A colorful ANSI color demonstration with Guacamole.""" from __future__ import absolute_import, print_function, unicode_literals from guacamole import Command class ANSIDemo(Command): """Demonstration of ANSI SGR codes.""" def invoked(self, ctx): """Method called when the command is invoked.""" if not ctx.ansi.is_enabled: print("You need color support to use this demo") else: print(ctx.ansi.cmd('erase_display')) self._demo_fg_color(ctx) self._demo_bg_color(ctx) self._demo_bg_indexed(ctx) self._demo_rgb(ctx) self._demo_style(ctx) def _demo_fg_color(self, ctx): self._header("Foreground Color", ctx) self._sub_header("Regular and Bright Foreground Sets", ctx) # Regular print(*[ctx.ansi('x' * (len(color) + 2), fg=color, bg='auto') for color in ctx.ansi.available_colors]) print(*[ctx.ansi(' {} '.format(color.upper()), fg=color, bg='auto') for color in ctx.ansi.available_colors]) print(*[ctx.ansi('x' * (len(color) + 2), fg=color, bg='auto') for color in ctx.ansi.available_colors]) # Bright print(*[ctx.ansi('x' * (len(color) + 2), fg='bright_{}'.format(color), bg='auto') for color in ctx.ansi.available_colors]) print(*[ctx.ansi(' {} '.format(color.upper()), fg='bright_{}'.format(color), bg='auto') for color in ctx.ansi.available_colors]) print(*[ctx.ansi('x' * (len(color) + 2), fg='bright_{}'.format(color), bg='auto') for color in ctx.ansi.available_colors]) def _demo_bg_color(self, ctx): self._header("Background Color", ctx) self._sub_header("Regular and Bright Background Sets", ctx) # Regular print(*[ctx.ansi(' ' * (len(color) + 2), bg=color) for color in ctx.ansi.available_colors]) print(*[ctx.ansi(' {} '.format(color.upper()), fg='auto', bg=color) for color in ctx.ansi.available_colors]) print(*[ctx.ansi(' ' * (len(color) + 2), bg=color) for color in ctx.ansi.available_colors]) # Bright print(*[ctx.ansi(' ' * (len(color) + 2), bg='bright_{}'.format(color)) for color in ctx.ansi.available_colors]) print(*[ctx.ansi(' {} '.format(color.upper()), fg='auto', bg='bright_{}'.format(color)) for color in ctx.ansi.available_colors]) print(*[ctx.ansi(' ' * (len(color) + 2), bg='bright_{}'.format(color)) for color in ctx.ansi.available_colors]) def _demo_bg_indexed(self, ctx): self._header("Indexed 8-bit Background Color", ctx) self._sub_header("Regular and Bright Color Subsets", ctx) print(*( [ctx.ansi(' ' * 4, bg=i) for i in range(0x00, 0x07 + 1)] + [ctx.ansi(' ' * 4, bg=i) for i in range(0x08, 0x0F + 1)])) print(*( [ctx.ansi('{:02X}'.format(i).center(4), fg='auto', bg=i) for i in range(0x00, 0x07 + 1)] + [ctx.ansi('{:02X}'.format(i).center(4), fg='auto', bg=i) for i in range(0x08, 0x0F + 1)])) print(*( [ctx.ansi(' ' * 4, bg=i) for i in range(0x00, 0x07 + 1)] + [ctx.ansi(' ' * 4, bg=i) for i in range(0x08, 0x0F + 1)])) self._sub_header("6 * 6 * 6 RGB color subset", ctx) for y in range(6 * 3): print(*( [' ' * 5] + [ctx.ansi('{:02X}'.format(i).center(4), fg='auto', bg=i) for i in range(0x10 + 6 * y, 0x10 + 6 * y + 6)] + [' ' * 6] + [ctx.ansi('{:02X}'.format(i).center(4), fg='auto', bg=i) for i in range(0x7c + 6 * y, 0x7c + 6 * y + 6)])) self._sub_header("24 grayscale colors", ctx) print( ' ', *[ctx.ansi(' ' * 6, bg=i) for i in range(0xE8, 0xF3 + 1)], sep='') print( ' ', *[ctx.ansi('{:02X}'.format(i).center(6), fg='auto', bg=i) for i in range(0xE8, 0xF3 + 1)], sep='') print( ' ', *[ctx.ansi(' ' * 6, bg=i) for i in range(0xE8, 0xF3 + 1)], sep='') print( ' ', *[ctx.ansi(' ' * 6, bg=i) for i in range(0xF4, 0xFF + 1)], sep='') print( ' ', *[ctx.ansi('{:02X}'.format(i).center(6), fg='auto', bg=i) for i in range(0xF4, 0xFF + 1)], sep='') print( ' ', *[ctx.ansi(' ' * 6, bg=i) for i in range(0xF4, 0xFF + 1)], sep='') def _demo_rgb(self, ctx): self._header("24 bit RGB Color", ctx) self._sub_header("The bar below only displays 80 unique colors", ctx) cols = 80 for y in range(3): print(*[ctx.ansi(' ', fg='auto', bg=hsv(360.0 / cols * i, 1, 1)) for i in range(cols)], sep='') def _demo_style(self, ctx): self._header("Text style", ctx) styles = ctx.ansi.available_styles print(*[ctx.ansi(style, style=style) for style in styles]) def _header(self, text, ctx): print( ctx.ansi(' ' * (40 - len(text) // 2), bg=0xE2), ctx.ansi(text, fg=0x10, bg=0xE2), ctx.ansi(' ' * (40 - len(text) // 2), bg=0xE2), sep='') def _sub_header(self, text, ctx): print( ctx.ansi(text, fg=0xFF, bg=0x10), ctx.ansi(' ' * (80 - len(text)), bg=0x10), sep='') def hsv(h, s, v): """Convert HSV (hue, saturation, value) to RGB.""" if 360 < h < 0: raise ValueError("h out of range: {}".format(h)) if 1 < s < 0: raise ValueError("s out of range: {}".format(h)) if 1 < v < 0: raise ValueError("v out of range: {}".format(h)) c = v * s # chroma h1 = h / 60 x = c * (1 - abs(h1 % 2 - 1)) if 0 <= h1 < 1: r1, g1, b1 = (c, x, 0) elif 1 <= h1 < 2: r1, g1, b1 = (x, c, 0) elif 2 <= h1 < 3: r1, g1, b1 = (0, c, x) elif 3 <= h1 < 4: r1, g1, b1 = (0, x, c) elif 4 <= h1 < 5: r1, g1, b1 = (x, 0, c) elif 5 <= h1 < 6: r1, g1, b1 = (c, 0, x) m = v - c r, g, b = r1 + m, g1 + m, b1 + m return int(r * 255), int(g * 255), int(b * 255) if __name__ == '__main__': ANSIDemo().main() guacamole-0.9.2/examples/hello-world.py0000775000175000017500000000366612522111232020054 0ustar zygazyga00000000000000#!/usr/bin/env python # encoding: utf-8 # # Copyright (c) 2015, Canonical Ltd. # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # 3. Neither the name of the copyright holder nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. """Hello World with Guacamole.""" from __future__ import absolute_import, print_function, unicode_literals from guacamole import Command class HelloWorld(Command): """A trivial hello-world command.""" def invoked(self, ctx): """Method called when the command is invoked.""" print("Hello World") if __name__ == '__main__': HelloWorld().main() guacamole-0.9.2/examples/fake-git.py0000775000175000017500000000601612522110401017300 0ustar zygazyga00000000000000#!/usr/bin/env python # encoding: utf-8 # # Copyright (c) 2015, Canonical Ltd. # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # 1. Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # # 3. Neither the name of the copyright holder nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS # IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, # THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR # PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR # CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR # PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. """A fake git-like command with Guacamole.""" from __future__ import absolute_import, print_function, unicode_literals from guacamole import Command class GitCommit(Command): """The 'git commit' command.""" def invoked(self, ctx): """Method called when the command is invoked.""" print("fake git commit") def register_arguments(self, parser): """ Guacamole method used by the argparse ingredient. :param parser: Argument parser (from :mod:`argparse`) specific to this command. """ parser.add_argument( '-m', '--message', metavar='', help="Use given as the commit message") class GitLog(Command): """The 'git log' command.""" def invoked(self, ctx): """Method called when the command is invoked.""" print("fake git log") def register_arguments(self, parser): """ Guacamole method used by the argparse ingredient. :param parser: Argument parser (from :mod:`argparse`) specific to this command. """ parser.add_argument( '--follow', action='store_true', help=( 'Continue listing the history of a file beyond renames' ' (works only for a single file).')) class Git(Command): """A fake git-like command.""" sub_commands = ( ('commit', GitCommit), ('log', GitLog) ) if __name__ == '__main__': Git().main() guacamole-0.9.2/docs/0000775000175000017500000000000012560714745014372 5ustar zygazyga00000000000000guacamole-0.9.2/docs/history.rst0000664000175000017500000000003312522077051016607 0ustar zygazyga00000000000000.. include:: ../HISTORY.rstguacamole-0.9.2/docs/authors.rst0000664000175000017500000000003312522077051016573 0ustar zygazyga00000000000000.. include:: ../AUTHORS.rstguacamole-0.9.2/docs/readme.rst0000664000175000017500000000003212522077051016342 0ustar zygazyga00000000000000.. include:: ../README.rstguacamole-0.9.2/docs/reference.rst0000664000175000017500000000174412532100726017053 0ustar zygazyga00000000000000============== Code Reference ============== :mod:`guacamole.core` ===================== .. automodule:: guacamole.core :members: Ingredient, Context, Bowl :mod:`guacamole.recipes` ======================== .. automodule:: guacamole.recipes :members: :mod:`guacamole.recipes.cmd` ============================ .. automodule:: guacamole.recipes.cmd :members: :mod:`guacamole.ingredients` ============================ .. automodule:: guacamole.ingredients :members: :mod:`guacamole.ingredients.cmdtree` ==================================== .. automodule:: guacamole.ingredients.cmdtree :members: :mod:`guacamole.ingredients.argparse` ===================================== .. automodule:: guacamole.ingredients.argparse :members: :mod:`guacamole.ingredients.crash` ================================== .. automodule:: guacamole.ingredients.crash :members: :mod:`guacamole.ingredients.ansi` ================================= .. automodule:: guacamole.ingredients.ansi :members: guacamole-0.9.2/docs/make.bat0000664000175000017500000001450212522110401015752 0ustar zygazyga00000000000000@ECHO OFF REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set BUILDDIR=_build set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . set I18NSPHINXOPTS=%SPHINXOPTS% . if NOT "%PAPER%" == "" ( set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% ) if "%1" == "" goto help if "%1" == "help" ( :help echo.Please use `make ^` where ^ is one of echo. html to make standalone HTML files echo. dirhtml to make HTML files named index.html in directories echo. singlehtml to make a single large HTML file echo. pickle to make pickle files echo. json to make JSON files echo. htmlhelp to make HTML files and a HTML help project echo. qthelp to make HTML files and a qthelp project echo. devhelp to make HTML files and a Devhelp project echo. epub to make an epub echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter echo. text to make text files echo. man to make manual pages echo. texinfo to make Texinfo files echo. gettext to make PO message catalogs echo. changes to make an overview over all changed/added/deprecated items echo. xml to make Docutils-native XML files echo. pseudoxml to make pseudoxml-XML files for display purposes echo. linkcheck to check all external links for integrity echo. doctest to run all doctests embedded in the documentation if enabled goto end ) if "%1" == "clean" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i del /q /s %BUILDDIR%\* goto end ) %SPHINXBUILD% 2> nul if errorlevel 9009 ( echo. echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo.installed, then set the SPHINXBUILD environment variable to point echo.to the full path of the 'sphinx-build' executable. Alternatively you echo.may add the Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from echo.http://sphinx-doc.org/ exit /b 1 ) if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end ) if "%1" == "dirhtml" ( %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. goto end ) if "%1" == "singlehtml" ( %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. goto end ) if "%1" == "pickle" ( %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the pickle files. goto end ) if "%1" == "json" ( %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the JSON files. goto end ) if "%1" == "htmlhelp" ( %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run HTML Help Workshop with the ^ .hhp project file in %BUILDDIR%/htmlhelp. goto end ) if "%1" == "qthelp" ( %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: echo.^> qcollectiongenerator %BUILDDIR%\qthelp\complexity.qhcp echo.To view the help file: echo.^> assistant -collectionFile %BUILDDIR%\qthelp\complexity.ghc goto end ) if "%1" == "devhelp" ( %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp if errorlevel 1 exit /b 1 echo. echo.Build finished. goto end ) if "%1" == "epub" ( %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub if errorlevel 1 exit /b 1 echo. echo.Build finished. The epub file is in %BUILDDIR%/epub. goto end ) if "%1" == "latex" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex if errorlevel 1 exit /b 1 echo. echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. goto end ) if "%1" == "latexpdf" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex cd %BUILDDIR%/latex make all-pdf cd %BUILDDIR%/.. echo. echo.Build finished; the PDF files are in %BUILDDIR%/latex. goto end ) if "%1" == "latexpdfja" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex cd %BUILDDIR%/latex make all-pdf-ja cd %BUILDDIR%/.. echo. echo.Build finished; the PDF files are in %BUILDDIR%/latex. goto end ) if "%1" == "text" ( %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text if errorlevel 1 exit /b 1 echo. echo.Build finished. The text files are in %BUILDDIR%/text. goto end ) if "%1" == "man" ( %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man if errorlevel 1 exit /b 1 echo. echo.Build finished. The manual pages are in %BUILDDIR%/man. goto end ) if "%1" == "texinfo" ( %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo if errorlevel 1 exit /b 1 echo. echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. goto end ) if "%1" == "gettext" ( %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale if errorlevel 1 exit /b 1 echo. echo.Build finished. The message catalogs are in %BUILDDIR%/locale. goto end ) if "%1" == "changes" ( %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes if errorlevel 1 exit /b 1 echo. echo.The overview file is in %BUILDDIR%/changes. goto end ) if "%1" == "linkcheck" ( %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck if errorlevel 1 exit /b 1 echo. echo.Link check complete; look for any errors in the above output ^ or in %BUILDDIR%/linkcheck/output.txt. goto end ) if "%1" == "doctest" ( %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest if errorlevel 1 exit /b 1 echo. echo.Testing of doctests in the sources finished, look at the ^ results in %BUILDDIR%/doctest/output.txt. goto end ) if "%1" == "xml" ( %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml if errorlevel 1 exit /b 1 echo. echo.Build finished. The XML files are in %BUILDDIR%/xml. goto end ) if "%1" == "pseudoxml" ( %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml if errorlevel 1 exit /b 1 echo. echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. goto end ) :endguacamole-0.9.2/docs/ingredients/0000775000175000017500000000000012560714745016705 5ustar zygazyga00000000000000guacamole-0.9.2/docs/ingredients/cmdtree.rst0000664000175000017500000002542412532100726021054 0ustar zygazyga00000000000000================== CommandTreeBuilder ================== Summary ======= Ingredient for arranging all the :class:`~guacamole.recipes.cmd.Command` classes into a tree of objects. Description =========== The command tree builder ingredient is a part of the command recipe. It is responsible for instantiating all sub-commands and arranging them into a tree for other ingredients to work with (most notably the argument parser ingredient). The secondary task is to add the *spices* requested by the top-level command to the bowl. This lets other ingredients act differently and effectively allows the top-level command to influence the runtime behavior of the whole recipe. Spices ====== This ingredient is not influenced by any *spices*. Context ======= This ingredient adds two objects to the context: ``cmd_tree`` A tree of tuples that describes all of the commands and their sub commands. ``cmd_toplevel`` The top-level command object. In addition, this ingredient inspects the *spieces* required by the top-level command and adds them to the bowl. .. todo:: Add a reference to an article about spices here. Command Line Arguments ====================== This ingredient is not exposing any command line arguments. Examples ======== Let's create two examples below. One for a simple command and another for a hierarchical command. This example will not use the full command recipe, to focus on the side effects of just the command tree builder ingredient. Flat Command ------------ We'll need a command object: .. doctest:: >>> from guacamole.recipes.cmd import Command >>> class HelloWorld(Command): ... pass Note that the tree builder is called with an *instance* of the command, not the class. This allows the top-level command to have a custom initializer, which might be helpful. .. doctest:: >>> from guacamole.core import Context >>> from guacamole.ingredients import cmdtree >>> ctx = Context() >>> cmdtree.CommandTreeBuilder(HelloWorld()).added(ctx) The context now has the ``cmd_toplevel`` object which is just the instance of the command we've used. .. doctest:: >>> ctx.cmd_toplevel Similarly, we'll have a tree of all the commands and their names in ``cmd_tree``: .. doctest:: >>> ctx.cmd_tree cmd_tree_node(cmd_name=None, cmd_obj=, children=()) The first element of the tuple is the effective command name. This can be used to rename a sub-command. Note that typically the ``command.name`` attribute is used (see :meth:`~guacamole.recipes.cmd.Command.get_cmd_name()`). The second element is the instance and the last element is a tuple of identical ``cmd_tree_node`` tuples, one for each of the sub-commands. We'll see how that looks like in the next example. Nested Commands --------------- We'll need a few commands for this example. Let's replicate the ``git``, ``git commit``, ``git stash``, ``git stash pop`` and ``git stash list`` commands. .. doctest:: >>> from guacamole.recipes.cmd import Command >>> class StashList(Command): ... pass >>> class StashPop(Command): ... pass >>> class Stash(Command): ... sub_commands = (('list', StashList), ('pop', StashPop)) >>> class Commit(Command): ... pass >>> class Git(Command): ... sub_commands = (('commit', Commit), ('stash', Stash)) Now, let's feed the ``Git`` class to the context. .. doctest:: >>> from guacamole.core import Context >>> from guacamole.ingredients import cmdtree >>> ctx = Context() >>> cmdtree.CommandTreeBuilder(Git()).added(ctx) The ``cmd_toplevel`` is as before (the ``Git`` *instance*). Let's look at the more interesting command tree. .. doctest:: :options: +NORMALIZE_WHITESPACE >>> ctx.cmd_tree cmd_tree_node(cmd_name=None, cmd_obj=, children=(cmd_tree_node(cmd_name='commit', cmd_obj=, children=()), cmd_tree_node(cmd_name='stash', cmd_obj=, children=(cmd_tree_node(cmd_name='list', cmd_obj=, children=()), cmd_tree_node(cmd_name='pop', cmd_obj=, children=()))))) Blah, that's mouthful. Let's see particular fragments to understand it better. .. doctest:: >>> ctx.cmd_tree.children[0].cmd_name 'commit' >>> ctx.cmd_tree.children[1].cmd_name 'stash' >>> ctx.cmd_tree.children[1].children[0].cmd_name 'list' >>> ctx.cmd_tree.children[1].children[1].cmd_name 'pop' Most of the time you won't have to use this data. Typically, it is consumed by the argument parser ingredient. Still, if you need it, here it is. ===================== CommandTreeDispatcher ===================== Summary ======= Ingredient for executing the :meth:`~guacamole.recipes.cmd.Command.invoked()` methods of all the commands that were selected by the user on command line. Description =========== This ingredient is responsible for invoking commands. It works during the dispatch phase of the application life-cycle. Since earlier stages can be interrupted it is not aways reached. E.g. when the application is invoked with the ``--help`` argument. The way this ingredient works is simple. It assumes that the argument parser creates a specific structure of references to command objects. The structure is stored in the ``argparse`` name-space object (which is available in ``ctx.args`` after the parsing phase. The structure is a sequence of attributes ``ctx.args.command0``, ``ctx.args.command1``, ``ctx.args.command2``, etc. The first one, ``ctx.args.command0`` is always present. Subsequent attributes are present if sub-commands are specified on the command line. For example, keeping our git sample in mind, the following command:: $ git stash Will result in ``ctx.args.command0`` instance of the `Git` command and ``ctx.args.command1`` an instance of the `GitStash` command. The dispatcher ingredient will invoke the ``command0``, look at the return value and then (most likely) proceed to ``command1`` (N+1 in general). The way return value is interpreted is interesting. In general, there are three cases: - None is interpreted as "nothing special happened". In the example above. The ``git stash`` will first call ``Git.invoked()``, see the (default) None and will proceed to call ``GitStash.invoked()``. - A generator is interpreted as a context-manager like. This allows, for example, the ``git`` command to use a context manager in its ``invoked()`` method to provide some managed resource to each sub-command. Note that the `invoked` method must behave as it if was decorated with ``@functools.contextmanager`` but it must not be actually decorated like that. - Any other return value is interpreted as an error code and stops recursive command dispatch. It will be finally returned from the ``main()`` method or raised as a ``SystemExit`` exception. Spices ====== This ingredient is not influenced by any *spices*. Context ======= This ingredient does not change the context. It does depend on the ``args`` object that is published by the argument parser ingredient. Command Line Arguments ====================== This ingredient is not exposing any command line arguments. Examples ======== Let's see how command invocation works in the few specific examples below. Single Command -------------- Let's start with a hello-world command first: .. doctest:: >>> from guacamole.recipes.cmd import Command >>> class HelloWorld(Command): ... def invoked(self, ctx): ... print("Hello World") Let's create the necessary infrastructure for using the dispatcher: .. doctest:: >>> import argparse >>> from guacamole.core import Context >>> from guacamole.ingredients import cmdtree >>> ctx = Context() >>> ctx.args = argparse.Namespace() Now let's run the `HelloWorld` command: .. doctest:: >>> ctx.args.command0 = HelloWorld() >>> cmdtree.CommandTreeDispatcher().dispatch(ctx) Hello World Success! The print worked and we also got the exit code (None, which is not printed by the repl). Next, let's implement the classic UNIX ``false(1)`` command: .. doctest:: >>> class false(Command): ... def invoked(self, ctx): ... return 1 Now, let's invoke it: .. doctest:: >>> ctx.args.command0 = false() >>> cmdtree.CommandTreeDispatcher().dispatch(ctx) 1 One. Also good. All command line tools return an exit code. If you actually run this command in the shell you can inspect the return code in several ways (depending on what is your shell). On Windows that is:: echo %ERRORLEVEL% And on all other systems, that are mostly using Bash by default:: echo $? In both cases, you should see ``1`` being printed by those echo statements. Nested Commands --------------- Let's expand the Git example to examine the context-manager-like behavior. .. doctest:: >>> class GitLibrary(object): ... def __enter__(self): ... print("Git initialized") ... return self ... def __exit__(self, *args): ... print("Git finalized") ... def commit(self): ... print("Using git to commit") >>> class Commit(Command): ... def invoked(self, ctx): ... with GitLibrary() as git: ... git.commit() >>> class Git(Command): ... sub_commands = (('commit', Commit),) Now, let's see what dispatch does here: .. doctest:: >>> ctx.args.command0 = Git() >>> ctx.args.command1 = Commit() >>> cmdtree.CommandTreeDispatcher().dispatch(ctx) Git initialized Using git to commit Git finalized If you have many commands that need to use some shared resource, you may be tempted to move the initialization to a shared code path. Guacamole allows you to do this by calling **all** the ``invoked()`` methods of all of the commands specified on command line. Let's modify the example to show this. The git library code will say as-is. The commit and git commands will be changed, to move the initialization code around. .. doctest:: >>> class Commit(Command): ... def invoked(self, ctx): ... ctx.git.commit() >>> class Git(Command): ... sub_commands = (('commit', Commit),) ... def invoked(self, ctx): ... with GitLibrary() as git: ... ctx.git = git ... yield Now, let's see what dispatch does now: .. doctest:: >>> ctx.args.command0 = Git() >>> ctx.args.command1 = Commit() >>> cmdtree.CommandTreeDispatcher().dispatch(ctx) Git initialized Using git to commit Git finalized No change, that's running exactly as before but now we can add more commands without duplicating the relevant code over and over. .. note:: Here, the finalization will happen even if something bad happens (e.g. ``Commit`` raising an exception). It's not useful often but it can be a way to use the context manager protocol with commands. guacamole-0.9.2/docs/ingredients/index.rst0000664000175000017500000000025312532100726020531 0ustar zygazyga00000000000000=========== Ingredients =========== This section contains documentation for each of the available ingredients. .. toctree:: :maxdepth: 2 ansi cmdtree crash guacamole-0.9.2/docs/ingredients/crash.rst0000664000175000017500000000167612532100726020534 0ustar zygazyga00000000000000=================== VerboseCrashHandler =================== Summary ======= Ingredient for handling crashing commands. Description =========== This ingredient mimics the default behavior of python for an uncaught exception. That is, to print the exception details, the function backtrace and to exit the process. Spices ====== This ingredient is not influenced by any *spices*. Context ======= This ingredient does not add any objects to the context. This ingredient does use the context though, to access the crash meta-data. This includes: ``exc_type`` The class of the exception that caused the application to crash. ``exc_value`` The exception object itself. ``traceback`` The traceback object. .. note:: The three attributes are automatically added by the :class:`~guacamole.core.Bowl` when something bad happens. Command Line Arguments ====================== This ingredient is not exposing any command line arguments. guacamole-0.9.2/docs/ingredients/ansi.rst0000664000175000017500000001145012560714334020364 0ustar zygazyga00000000000000==== ANSI ==== Summary ======= Ingredient for working with ANSI Control Codes Description =========== The ANSI ingredient exposes ANSI control codes in a simple way. ANSI codes can be used to control text color and style on compatible terminals. Linux terminal emulators commonly support a wide subset of control codes. Particular support differs between the classic Linux console, *Xterm*, *gnome-terminal* and *konsole* (and the backing libraries). Some features are supported more widely than others. In particular, the text console is rather limited and will likely remain so until the systemd-based replacement is commonly used. The terminal emulator included in Apple's OS X supports a subset of the features (3rd party terminal emulators for OS X were not tested, contributions are welcome). In general you can treat OS X like a poor version of Linux. The windows command prompt is the most limited environment as it only support several foreground and background colors and nothing else at all. It also has issues with Unicode (as in, it doesn't support it at all). On Windows, usage of ANSI depends on the availability of ``colorama``. Colorama is a third party library that wraps ``sys.stdout`` and ``sys.stderr``, parses ANSI control codes and converts them to the corresponding Windows API calls. Spices ====== This ingredient is not influenced by any *spices*. Context ======= This ingredient adds two objects to the context: ``ansi`` An instance of :class:`~guacamole.ingredients.ansi.ANSIFormatter`. The object is automatically configured (disabled) when the extra control codes are undesired (stdout not attached to a terminal emulator). ``aprint`` The :meth:`~guacamole.ingredients.ansi.ANSIFormatter.aprint` method, as a shorthand for ``ctx.ansi.aprint``. Command Line Arguments ====================== This ingredient is not exposing any command line arguments. Examples ======== Let's construct a simple example. Note that typically you will use the context that is provided to you from the :meth:`~guacamole.recipes.cmd.Command.invoked()` method of a command. .. doctest:: >>> from guacamole.core import Context >>> from guacamole.ingredients import ansi >>> ctx = Context() >>> ansi.ANSIIngredient(enable=True).added(ctx) The context now has the ``ansi`` object, which is an instance of :class:`~guacamole.ingredients.ansi.ANSIFormatter`. It has some methods and properties that we'll see below but it is also callable and darn convenient to use. You can use the ``fg`` and ``bg`` keyword arguments to control the *foreground* and *background* text color respectively. .. doctest:: >>> str(ctx.ansi('red on blue', fg='red', bg='blue')) '\x1b[31;44mred on blue\x1b[0m' You can use keyword arguments that correspond to *each* of the countless ``sgr_`` constants available in the class :class:`~guacamole.ingredients.ansi.ANSI`. Here, let's get bold text using the :attr:`~guacamole.ingredients.ansi.ANSI.sgr_bold` code. .. doctest:: >>> str(ctx.ansi('bold text', bold=1)) '\x1b[1mbold text\x1b[0m' In some cases you may want to use different code knowing that the output will be colorized (e.g. use color codes instead of longer text labels). You can achieve that by testing :meth`~guacamole.ingredients.ansi.ANSI.is_enabled`. .. doctest:: >>> # Let's disable the ANSI support for this test >>> ansi.ANSIIngredient(enable=False).added(ctx) >>> if ctx.ansi.is_enabled: ... ctx.aprint('!!!', fg='red') ... else: ... ctx.aprint('ALARM') ALARM Expressing colors ================= Guacaomle supports several styles of colors: - Named colors represented as strings: * ``"black"`` * ``"red"`` * ``"green"`` * ``"yellow"`` * ``"blue"`` * ``"magenta"`` * ``"cyan"`` * ``"white"`` - Bright variant of named colors (not repeated) - Indexed colors represented as an integer in range(256): * 0x00-0x07: standard colors (as in ``ESC [ 30–37 m``) * 0x08-0x0F: high intensity colors (as in ``ESC [ 90–97 m``) * 0x10-0xE7: 6 × 6 × 6 = 216 colors: 16 + 36 × r + 6 × g + b (0 ≤ r, g, b ≤ 5) * 0xE8-0xFF: grayscale from black to white in 24 steps - RGB colors represented as (r, g, b) where each component is an integer in range(256) - The special value ``"auto"`` which picks the complementary (readable) variant. Auto may be used in one of ``fg=`` or ``bg=`` if ``bg=`` or ``fg=`` (respectively) are using a concrete color. .. note:: The actual colors behind the string-named colors vary between different terminal emulators. Sometimes the color is just slightly different. Sometimes it is just totally unrelated to the one specified in the ANSI standard. .. warning:: RGB colors are not supported on Windows and OS X. They are only supported on modern terminal emulators, typically on Linux distributions. guacamole-0.9.2/docs/usage/0000775000175000017500000000000012560714745015476 5ustar zygazyga00000000000000guacamole-0.9.2/docs/usage/concepts.rst0000664000175000017500000000420612532100726020033 0ustar zygazyga00000000000000.. _bundled_ingredients: Recipes, Ingredients and Spices =============================== Guacamole is a framework for creating command line applications. To understand how to use it, you need to know about the three concepts (recipes, ingredients and spices). They define how guacamole works (tastes) and they are how you can make guacamole work for you in new and interesting ways. Ingredients ----------- Ingredients are pluggable components that can be added to a guacamole recipe. They have well-defined APIs and are invoked by guacamole during the lifetime of the application. You can think of ingredients as of middleware or a fancy context manager. For an in-depth documentation see the :class:`~guacamole.core.Ingredient` class. For a list of bundled ingredients (batteries included) please see `bundled-ingredients`. **Guacamole uses ingredients to avoid having complex, convoluted core. The core literally does nothing more than to invoke all ingredients in a given order. Applications use ingredietns indirectly, through recipes.** Spices ------ Spices are small, optional bits of taste that can be added along with a given ingredient. They are just a feature flag with a fancy name. You will see spices documented along with each ingredient. For many features you will use the sane defaults that guacamole aims to provide but sometimes you may want to tweak something. Such elements can be hidden behind an ingredient. **Guacamole uses spices to offer fixed cusomizability where it makes sense to do so. Applications say witch spices they wish to use. Spices always enable non-default behavior.** Recipes ------- Recipes define the sequence of ingredients to use for a tasty guacamole. In reality a recipe is a simple function that returns a list of ingredient instances to use in a given application. **Guacamole uses recipes to offer easy-to-use, well-designed patterns for creating applications. Anyone can create a recipe that uses a set of ingredients that fit a particular purpose.** Command? -------- The :class:`~guacamole.recipes.cmd.Command` class is just a recipe that uses a set of ingredients. As Guacamole matures, other recipes may be added. guacamole-0.9.2/docs/usage/philosophy.rst0000664000175000017500000000721612532100726020417 0ustar zygazyga00000000000000==================== Philosophy Statement ==================== The power of Guacamole is based on the simplicity of conventions and sane defaults. Let's talk about some of the conventions that are followed here. .. note:: You will see how the philosophy turns into practice in the command turtorial section. Defaults Matter =============== Important things make nice applications and tools behave better than random, ad-hoc scripts that have no consistency and happily crash on anything unexpected. Guacamole strives to enable important things that make using applications pleasant. By default Guacamole will: - Expose detailed help and usage messages. - Use translated messages for everything it does. - Handle logging for you so that it is useful. - Handle crashes for you so that users can send feedback. - Use the right directories in your filesystem. - Use color-coded information, if supported, for readability. - Teach you, the developer, if you make a mistake that it can detect. Some defaults say to turn a feature off. Guacamole uses *spices* to let developers opt-into those features that they wish to use. You will learn about spices later in this document. For now just remember that they are equivalent to feature flags. Documentation Is Important ========================== Documentation is the most important thing you can get wrong easily. You can create perfect tools that do some operation correctly and efficiently but it will all go to waste if nobody can use your product. Guacamole encourages developers to write useful documentation. The most basic form of documentation is the *docstring*. The docstring is powerful. You see it while writing your code. Other people can see it by various means, using tools like ``pydoc`` or by reading a document generated with a tool like sphinx. Guacamole has rich support for documentation. By default, a lot of information is extracted from your command docstrings. You can reuse all of that, for free, to create proper manual pages. Quality tools come with documentation and command line tools use manual pages as the most common, most discoverable means of learning about a particular program. Internationalization is Important ================================= Internationalization is important to many users. While many developers and system administrators are comfortable with reading English it is strongly recommended to support localization. Modern software gets this right. Guacamole supports internationalization by default. Commands can advertise their gettext domain using the ``gettext_domain`` attribute (see :meth:`~guacamole.recipes.cmd.Command.get_gettext_domain()` for details). Guacamole will carefully work with your docstrings to feed them to gettext and extract the useful bits out. Commands can mix-and-match different gettext domains without issues. If you are writing a non-trivial application which is composed of commands coming from various sources they will all work correctly together. Convention over Configuration ============================= Guacamole has a lot of APIs. Most of the time you won't have to work with them. Guacamole will reuse information that you can provide without defining methods. This is how the docstrings are used for documentation. This is how you can define numerous attributes to describe specific features of your commands. Instead of working with the methods you can just define an item. This has the advantage that Guacamole can look at your command class and can educate you if you make a mistake. This is easier to work with than reading through back-traces or working with type annotations that may or may not be enough to capture something you want to express. guacamole-0.9.2/docs/usage/index.rst0000664000175000017500000000130012532100726017314 0ustar zygazyga00000000000000===== Usage ===== .. warning:: Documentation is under construction. For now please refer to the ``examples/`` directory in the source distribution. There are two layers that you might be interested in. You can either use the existing recipes, most notably, the Command recipe. This is the best way to get started with Guacamole and get advantage of the code that is here already. The second layer is useful once you start to feel comfortable with the code and want to get more features or perhaps convert your custom code over to work with Guacamole. Both layers are documented below but first read the philosophy statement. .. toctree:: :maxdepth: 2 philosophy concepts recipes guacamole-0.9.2/docs/usage/recipes.rst0000664000175000017500000001612112532100726017646 0ustar zygazyga00000000000000.. _commands: =================== Using Stock Recipes =================== The Command Recipe ================== The command recipe contains the distilled, correct behavior for command line applications. The main face of the command recipe is the :class:`~guacamole.recipes.cmd.Command` class. .. note:: Guacamole values conventions. Instead of overriding many of the methods that comprise the Command class, you can just define a variable that will take priority. This leads to shorter and more readable code. Defining commands ----------------- Let's build a simple hello-world example again: .. testsetup:: import guacamole .. doctest:: >>> class HelloWorld(guacamole.Command): ... def invoked(self, ctx): ... print("Hello World!") The central entry point of each command is the :meth:`~guacamole.recipes.cmd.Command.invoked()` method. The method is called once the command is ready to be dispatched. This is what you would put inside your ``main()`` function, after the boiler-plate code that Guacamole handles for you. What you do here is up to you. For now, let's just run our simple example with the convenience method :meth:`~guacamole.recipes.cmd.Command.main()`. Note that here we're passing extra arguments to control how the tool executes, normally you would just call main without any arguments and it will do the right thing. .. doctest:: >>> HelloWorld().main([], exit=False) Hello World! 0 For now let's ignore the argument `ctx`. It is extremely handy, as we will see shortly, but we don't need it yet. .. note:: This little example is available in the ``examples/`` directory in the source distribution. The version of Guacaomle packaged in Debian has them in the directory ``/usr/share/doc/python-guacamole-doc/examples``. As the directory name implies, you have to install the ``python-guacamole-doc`` package to get them. Do use the example and play around with it, see how it behaves if you run it with various arguments. The idea is that Guacamole is supposed to create *good* command line applications. Good applications do the right stuff internally. The ``hello-world`` example is trivial but we'll see more of what is going on internally soon. Working with arguments & The Context ------------------------------------ Commands typically take arguments. To say which arguments are understood by our command we need to implement the second method :meth:`~guacamole.recipes.cmd.Command.register_arguments()`. This method is called with the familiar :py:class:`argparse.ArgumentParser` instance. You've seen this code over and over, here you should just focus on configuring the arguments and options. Guacamole handles the parser for you. .. doctest:: >>> class HelloWorld(guacamole.Command): ... def register_arguments(self, parser): ... parser.add_argument('name') ... def invoked(self, ctx): ... print("Hello {0}!".format(ctx.args.name)) As you can see, the context is how you reach the command line arguments parsed by `argparse`. What else is there you might ask? The answer is *everything*. The context is how *ingredients* can expose useful capabilities to commands. The command recipe is comprised of several ingredients, as you will later see. One of those ingredients parsers command line arguments and adds the results to the context as the ``args`` object. .. note:: When reading documentation about particular ingredients make sure to see how they interact with the context. Each ingredient documents that clearly. Let's run our improved command and see what happens: .. doctest:: >>> HelloWorld().main(["Guacamole"], exit=False) Hello Guacamole! 0 No surprises there. We can see that the command printed the hello message and then returned the exit code ``0``. The exit code is normally passed to the system so that your application can be scripted. .. note:: Guacamole will return ``0`` for you if you don't return anything. If you do return a value we'll just preserve it for you. You can also raise SystemExit with any value and we'll do the right thing yet again. This should be all quite familiar to everyone so we won't spend more time on arguments now. You can read the :py:ref:`argparse-tutorial` if you want. A small digression, why argparse? --------------------------------- By default, all command line parsing is handled by :py:mod:`argparse`. Guacamole doesn't force you to use argparse (nothing really is wired to depend on it in the core) but the stock set of ingredients do use it. Argparse is familiar to many developers and by having it by default you can quickly convert your application code over to guacamole without learning two new things at a time. Nesting Commands ---------------- Many common tools expose everything from a top-level command, e.g. ``git commit``. Here, ``git`` gets invoked, looks at the command line arguments and delegates the dispatching to the ``git-commit`` command. All Guacamole commands can be nested. Let's build a quick git-like command to see how to do that. .. doctest:: >>> class git_commit(guacamole.Command): ... name = 'commit' ... def invoked(self, ctx): ... print("commit invoked") >>> class git_log(guacamole.Command): ... def invoked(self, ctx): ... print("log invoked") >>> class git(guacamole.Command): ... name = 'git' ... sub_commands = ( ... (None, git_commit), ... ('log', git_log), ... ) As you see it's all based on declarations. Each command now cares about the name it is using. Names can be assigned in the ``sub_commands`` list or individually in each class, by defining the ``name`` attribute. The name listed in sub_commands takes precedence over the name defined in the class. Here, the ``git_log`` command doesn't define a ``name`` so we provide one explicitly as the first element of the pair, as sequence of which is stored in ``sub_commands``. .. note:: Behind the scenes Guacamole actually calls a number of methods for everything. See :meth:`~guacamole.recipes.cmd.Command.get_sub_commands()` and :meth:`~guacamole.recipes.cmd.Command.get_cmd_name()` for the two used here. There are *many* more methods though. Let's invoke our fake git to see how that works now: .. doctest:: >>> git().main(["commit"], exit=False) commit invoked 0 >>> git().main(["log"], exit=False) log invoked 0 So far everything behaves as expected. Let's see what happens if we run something that we've not coded: .. doctest:: >>> git().main(["status"], exit=False) 2 This won't fit the *doctest* above (it's printed on stderr) but in reality the application will also say something like this:: usage: git [-h] {commit,log} ... setup.py: error: invalid choice: 'status' (choose from 'commit', 'log') .. note:: Technically the :class:`~guacamole.recipes.cmd.Command` class has numerous methods. Most of those methods are of no interest to most of the developers. Feel free to read the API reference later if you are interested. guacamole-0.9.2/docs/index.rst0000664000175000017500000000041312532100726016214 0ustar zygazyga00000000000000Guacamole ========= Contents: .. toctree:: :maxdepth: 2 readme installation usage/index ingredients/index contributing authors history reference Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` guacamole-0.9.2/docs/conf.py0000664000175000017500000002202212532100726015652 0ustar zygazyga00000000000000#!/usr/bin/env python # -*- coding: utf-8 -*- # # complexity documentation build configuration file, created by # sphinx-quickstart on Tue Jul 9 22:26:36 2013. # # This file is execfile()d with the current directory set to its # containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys import os # If extensions (or modules to document with autodoc) are in another # directory, add these directories to sys.path here. If the directory is # relative to the documentation root, use os.path.abspath to make it # absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) # Get the project root dir, which is the parent dir of this cwd = os.getcwd() project_root = os.path.dirname(cwd) # Insert the project root dir as the first element in the PYTHONPATH. # This lets us ensure that the source package is imported, and that its # version is used. sys.path.insert(0, project_root) import guacamole # -- General configuration --------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] # Use the python documentation website by default py_intersphinx = 'https://docs.python.org/{}.{}'.format( *sys.version_info[0:2]) if sys.platform.startswith('linux'): # On Linux, a pre-installed documentation will be used, if available location_debian = '/usr/share/doc/python{}.{}/html/'.format( *sys.version_info[0:2]) location_fedora3 = '/usr/share/doc/python-docs/html/' location_fedora2 = '/usr/share/doc/python3-docs/html/' for location in (location_debian, location_fedora2, location_fedora3): if os.path.isfile(location): py_intersphinx = 'file://{}'.format(location) break intersphinx_mapping = { 'python': (py_intersphinx, None), } # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'Guacamole' copyright = u'2014, Zygmunt Krynicki' # The version info for the project you're documenting, acts as replacement # for |version| and |release|, also used in various other places throughout # the built documents. # # The short X.Y version. version = guacamole.__version__ # The full version, including alpha/beta/rc tags. release = guacamole.__version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to # some non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all # documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] # If true, keep warnings as "system message" paragraphs in the built # documents. #keep_warnings = False # -- Options for HTML output ------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a # theme further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as # html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the # top of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon # of the docs. This file should be a Windows icon file (.ico) being # 16x16 or 32x32 pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) # here, relative to this directory. They are copied after the builtin # static files, so a file named "default.css" will overwrite the builtin # "default.css". html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page # bottom, using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} # Additional templates that should be rendered to pages, maps page names # to template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. # Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. # Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages # will contain a tag referring to it. The value of this option # must be the base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'guacamoledoc' # -- Options for LaTeX output ------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass # [howto/manual]). latex_documents = [ ('index', 'guacamole.tex', u'Guacamole Documentation', u'Zygmunt Krynicki', 'manual'), ] # The name of an image file (relative to this directory) to place at # the top of the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings # are parts, not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output ------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'guacamole', u'Guacamole Documentation', [u'Zygmunt Krynicki'], 1) ] # If true, show URL addresses after external links. #man_show_urls = False # -- Options for Texinfo output ---------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ('index', 'guacamole', u'Guacamole Documentation', u'Zygmunt Krynicki', 'guacamole', 'Command line tool library for Python.', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] # If false, no module index is generated. #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False guacamole-0.9.2/docs/contributing.rst0000664000175000017500000000006412532100726017616 0ustar zygazyga00000000000000.. _contributing: .. include:: ../CONTRIBUTING.rst guacamole-0.9.2/docs/Makefile0000664000175000017500000001517112522110401016010 0ustar zygazyga00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) endif # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" @echo " xml to make Docutils-native XML files" @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/complexity.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/complexity.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @echo "# mkdir -p $$HOME/.local/share/devhelp/complexity" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/complexity" @echo "# devhelp" epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." latexpdfja: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through platex and dvipdfmx..." $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." xml: $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml @echo @echo "Build finished. The XML files are in $(BUILDDIR)/xml." pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."guacamole-0.9.2/docs/installation.rst0000664000175000017500000000276712532100726017624 0ustar zygazyga00000000000000============ Installation ============ The recommended installation method varies per platform. In general ``pip``-based installs work everywhere but it is recommended to use other methods if possible. Linux Distributions =================== Debian (and derivatives) ------------------------ Install either ``python-guacamole`` or ``python3-guacamole`` (preferred) using your preferred package manager front-end. An off-line copy of the documentation is available in the ``python-guacamole-doc`` package. The same package includes all of the bundled examples. .. note:: The version of Guacamole available in Debian might not be the most recent version but it was manually reviewed by Debian maintainers. The Debian archive contains cryptographically strong integrity and security guarantees. This method of installation is more trustworthy (and harder to attack) than the one used by pip. Fedora (and derivatives) ------------------------ Currently there is no version of Guacamole packaged and available for Fedora. A *copr* repository might be created if there is demand. Proper integration into the Fedora archive is on the roadmap but was not attempted at this time. Other distributions ------------------- There are no other packages as of this writing. Please contribute one if you can. See the :ref:`contributing` for details. Other platforms =============== At the command line run:: $ pip install guacamole .. note:: This section applies to all versions of Windows and OS X. guacamole-0.9.2/CONTRIBUTING.rst0000664000175000017500000000625012532100726016071 0ustar zygazyga00000000000000============ Contributing ============ Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. You can contribute in many ways: Types of Contributions ---------------------- Report Bugs ~~~~~~~~~~~ Report bugs at https://github.com/zyga/guacamole/issues. If you are reporting a bug, please include: * Your operating system name and version. * Any details about your local setup that might be helpful in troubleshooting. * Detailed steps to reproduce the bug. Fix Bugs ~~~~~~~~ Look through the GitHub issues for bugs. Anything tagged with "bug" is open to whoever wants to implement it. Implement Features ~~~~~~~~~~~~~~~~~~ Look through the GitHub issues for features. Anything tagged with "feature" is open to whoever wants to implement it. Write Documentation ~~~~~~~~~~~~~~~~~~~ Guacamole could always use more documentation, whether as part of the official Guacamole docs, in docstrings, or even on the web in blog posts, articles, and such. Submit Feedback ~~~~~~~~~~~~~~~ The best way to send feedback is to file an issue at https://github.com/zyga/guacamole/issues. If you are proposing a feature: * Explain in detail how it would work. * Keep the scope as narrow as possible, to make it easier to implement. * Remember that this is a volunteer-driven project, and that contributions are welcome :) Get Started! ------------ Ready to contribute? Here's how to set up `guacamole` for local development. 1. Fork the `guacamole` repo on GitHub. 2. Clone your fork locally:: $ git clone git@github.com:your_name_here/guacamole.git 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:: $ mkvirtualenv guacamole $ cd guacamole/ $ python setup.py develop 4. Create a branch for local development:: $ git checkout -b name-of-your-bugfix-or-feature Now you can make your changes locally. 5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox:: $ flake8 guacamole $ python setup.py test $ tox To get flake8 and tox, just pip install them into your virtualenv. 6. Commit your changes and push your branch to GitHub:: $ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature 7. Submit a pull request through the GitHub website. Pull Request Guidelines ----------------------- Before you submit a pull request, check that it meets these guidelines: 1. The pull request should include tests. 2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst. 3. The pull request should work for Python 2.7, 3.2, 3.3, and 3.4, and for PyPy. Check https://travis-ci.org/zyga/guacamole/pull_requests and make sure that the tests pass for all supported Python versions. Tips ---- To run a subset of tests:: $ python -m unittest guacamole.test_core (Where guacamole.test_core is the module with tests you want to run) guacamole-0.9.2/setup.py0000775000175000017500000000623212560714506015155 0ustar zygazyga00000000000000#!/usr/bin/env python # encoding: utf-8 # # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """setup for guacamole.""" import sys try: from setuptools import setup except ImportError: from distutils.core import setup readme = open('README.rst').read() history = open('HISTORY.rst').read().replace('.. :changelog:', '') setup( name='guacamole', version='0.9.2', description='Guacamole is an command line tool library for Python', long_description=readme + '\n\n' + history, author='Zygmunt Krynicki', author_email='me@zygoon.pl', url='https://github.com/zyga/guacamole', packages=['guacamole', 'guacamole.ingredients', 'guacamole.recipes'], package_dir={'guacamole': 'guacamole'}, include_package_data=True, license="LGPLv3", zip_safe=True, keywords='argparse cli tool command sub-command subcommand', tests_require=([ # XXX: we don't depend on funcsigs but apparently mocks does without # properly declaring it. When I run ./setup.py test on Python 2.7 I get # an import error on mock, failing to import funcsigs. Oddly enough # explicitly installing mock installs funcsigs. # # If this doesn't happen later, feel free to remove funcsigs. 'funcsigs', 'mock', 'unittest2' if sys.version_info[0] == 2 else 'unittest2py3k', ] if sys.version_info[:2] <= (3, 3) else None), classifiers=[ 'Development Status :: 3 - Alpha', 'Intended Audience :: Developers', 'Environment :: Console', ('License :: OSI Approved :: GNU Lesser General Public License v3' ' (LGPLv3)'), 'Natural Language :: English', 'Natural Language :: Polish', 'Operating System :: MacOS :: MacOS X', 'Operating System :: Microsoft :: Windows :: Windows 7', 'Operating System :: Microsoft :: Windows :: Windows XP', 'Operating System :: POSIX', 'Operating System :: POSIX :: Linux', 'Topic :: Software Development', 'Topic :: Software Development :: Libraries', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.2', 'Programming Language :: Python :: 3.3', 'Programming Language :: Python :: 3.4', 'Programming Language :: Python :: Implementation :: CPython', 'Programming Language :: Python :: Implementation :: PyPy', ], test_suite='guacamole', ) guacamole-0.9.2/README.rst0000664000175000017500000000323412532100726015116 0ustar zygazyga00000000000000============================================================ Guacamole - Framework for Creating Command Line Applications ============================================================ .. image:: https://badge.fury.io/py/guacamole.png :target: http://badge.fury.io/py/guacamole .. image:: https://travis-ci.org/zyga/guacamole.png?branch=master :target: https://travis-ci.org/zyga/guacamole .. image:: https://pypip.in/d/guacamole/badge.png :target: https://pypi.python.org/pypi/guacamole Tools, done right ================= Guacamole is a LGPLv3 licensed toolkit for creating good command line applications. Guacamole that does the right things for you and makes writing applications easier. .. testsetup:: import guacamole .. doctest:: >>> class HelloWorld(guacamole.Command): ... """A simple hello-world application.""" ... def register_arguments(self, parser): ... parser.add_argument('name') ... def invoked(self, ctx): ... print("Hello {0}!".format(ctx.args.name)) Running it directly is as simple as calling ``main()``: .. doctest:: >>> HelloWorld().main(['Guacamole'], exit=False) Hello Guacamole! 0 What you didn't have to do is what matters: - configure the argument parser - define and setup application logging - initialize internationalization features - add debugging facilities - write a custom crash handler Features ======== * Free software: LGPLv3 license * Documentation: https://guacamole.readthedocs.org. * Create command classes and run them from command line. * Group commands to create complex tools. * Use recipes, ingredients and spices to customize behavior guacamole-0.9.2/HISTORY.rst0000664000175000017500000000143612560714370015333 0ustar zygazyga00000000000000.. :changelog: History ======= 0.9.2 (2015-08-06) ------------------ * Fix https://github.com/zyga/guacamole/issues/11 0.9.1 (2015-08-06) ------------------ * Fix https://github.com/zyga/guacamole/issues/9 0.9 (2015-05-11) ---------------- * Vastly improved documentation * Bugfixes and changes based on early feedback * New cmdtree module with two ingredients (for instantiating commands and for dispatching the invoked method) * Simplified argparse ingredient (for just handling parser) * Unit tests and doctests for some of the functionality 0.8 (2015-04-21) ---------------- * First release on PyPI. 2012-2015 --------- * Released on PyPI as a part of plainbox as ``plainbox.impl.clitools``, ``plainbox.impl.logging``, ``plainbox.i18n`` and ``plainbox.impl.secure.plugins``. guacamole-0.9.2/guacamole/0000775000175000017500000000000012560714745015377 5ustar zygazyga00000000000000guacamole-0.9.2/guacamole/recipes/0000775000175000017500000000000012560714745017031 5ustar zygazyga00000000000000guacamole-0.9.2/guacamole/recipes/cmd.py0000664000175000017500000003341312560712471020144 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """ Recipe for using guacamole to run commands. This module contains sock recipes for guacamole. Stock recipes allow application developers to use use simple-to-understand design patterns to get predictable runtime behiavior. Currently, guacamole ships with two such recipes, for creating simple commands and for creating hierarhical command groups. They are captured by the :class:`Command` and :class:`Group` classes respectively. """ from __future__ import absolute_import, print_function, unicode_literals import gettext import inspect import logging from guacamole.ingredients import ansi from guacamole.ingredients import argparse from guacamole.ingredients import cmdtree from guacamole.ingredients import crash from guacamole.recipes import Recipe __all__ = ( 'Command', 'CommandRecipe', ) _logger = logging.getLogger('guacamole') class Command(object): """ A single-purpose command. Single purpose commands are the most commonly known tools in command line environments. Tools such as ``ls``, ``mkdir`` or ``vim`` all fall in this class. A command is essentially a named action that can be invoked from the terminal emulator or other command line environment specific to a given operating system. To create a new command simply create a custom class and override the :meth:`invoked()` method. Put all of your custom code there. If you want to interact with command line arguments then please also override the :meth:`register_arguments()` method. Have a look at example applications for details of how to do this. You can use them as a starting point for your own application as they are licensed very liberally. """ def __repr__(self): """Get the debugging representation of a command.""" return "<{}>".format(self.__class__.__name__) def invoked(self, context): """ Callback called when the command gets invoked. :param context: The guacamole context object. :returns: The return value is returned by the executable. It should be an integer between 0 and 255. Other values are will likely won't work at all. The context argument can be used to access command line arguments and other information that guacamole provides. """ if not self.get_sub_commands(): _logger.warning( "Command %r doesn't override Command.invoked()", self) def register_arguments(self, parser): """ Callback called to register command-specific arguments. :param parser: Argument parser (from :mod:`argparse`) specific to this command. """ def get_app_vendor(self): """ Get the name of the application vendor. The name should be a human readable name, like ``"Joe Developer"`` or ``"Big Corporation Ltd."`` .. note:: Application vendor name is looked up using the ``app_vendor`` attribute. """ try: return self.app_vendor except AttributeError: pass def get_app_name(self): """ Get the name of the application. .. note:: Application name is looked up using the ``app_name`` attribute. Application name differs from executable name. The executable might be called ``my-app`` or ``myapp`` while the application might be called ``My Application``. """ try: return self.app_name except AttributeError: pass def get_app_id(self): """ Get the identifier of the application. .. note:: Application identifier is looked up using the ``app_id`` attribute. The syntax of a valid command identifier is ``REVERSE-DNS-NAME:ID``. For example, ``"com.example.product:command"``. This identifier must not contain characters that are hostile to the file systems. It's best to stick to ASCII characters and digits. On *Mac OS X* this will be used as a directory name rooted in ``~/Library/Preferences/``. On Linux and other freedesktop.org-based systems this will be used as directory name rooted in ``$XDG_CONFIG_HOME`` and ``$XDG_CACHE_HOME``. On Windows it will be used as a directory name rooted in the per-user ``AppData`` folder. .. note:: If this method returns None then logging and configuration services are disabled. It is strongly recommended to implement this method and return a correct value as it enhances application behavior. """ try: return self.app_id except AttributeError: pass def get_cmd_name(self): """ Get the name of the application executable. .. note:: If this method returns None then the executable name is guessed from ``sys.argv[0]``. """ try: return self.name except AttributeError: pass def get_cmd_version(self): """ Get the version reported by this executable. .. note:: If this method returns None then the ``--version`` option is disabled. """ try: return self.version except AttributeError: pass def get_cmd_usage(self): """ Get the usage string associated with this command. :returns: ``self.usage``, if defined :returns: None, otherwise The usage string typically contains the list of available, abbreviated options, mandatory arguments and other arguments. Its purpose is to quickly inform the user on the basic syntax used by the command. It is perfectly fine not to customize this method as the default is to compute an appropriate usage string out of all the arguments. Consider implementing this method in a customized way if your command has highly complicated syntax and you want to provide an alternative, more terse usage string instead. """ try: return self.usage except AttributeError: pass def get_cmd_help(self): """ Get the single-line help of this command. :returns: ``self.help``, if defined :returns: The first line of the docstring, without the trailing dot, if present. :returns: None, otherwise """ try: return self.help except AttributeError: pass try: return get_localized_docstring( self, self.get_gettext_domain() ).splitlines()[0].rstrip('.').lower() except (AttributeError, IndexError, ValueError): pass def get_cmd_description(self): """ Get the leading, multi-line description of this command. :returns: ``self.description``, if defined :returns: A substring of the class docstring between the first line (which is discarded) and the string ``@EPILOG@``, if present, or the end of the docstring, if any :returns: None, otherwise The description string will be displayed after the usage string but before any of the detailed argument descriptions. Please consider following good practice by keeping the description line short enough not to require scrolling but useful enough to provide additional information that cannot be inferred from the name of the command or other arguments. Stating the purpose of the command is highly recommended. """ try: return self.description except AttributeError: pass try: return '\n'.join( get_localized_docstring( self, self.get_gettext_domain() ).splitlines()[1:] ).split('@EPILOG@', 1)[0].strip() except (AttributeError, IndexError, ValueError): pass def get_cmd_epilog(self): """ Get the trailing, multi-line description of this command. :returns: ``self.epilog``, if defined :returns: A substring of the class docstring between the string ``@EPILOG`` and the end of the docstring, if defined :returns: None, otherwise The epilog is similar to the description string but it is instead printed after the section containing detailed descriptions of all of the command line arguments. Please consider following good practice by providing additional details about how the command can be used, perhaps an example or a reference to means of finding additional documentation. """ try: return self.source.epilog except AttributeError: pass try: return '\n'.join( get_localized_docstring( self, self.get_gettext_domain() ).splitlines()[1:] ).split('@EPILOG@', 1)[1].strip() except (AttributeError, IndexError, ValueError): pass def get_gettext_domain(self): """ Get the gettext translation domain associated with this command. The value returned will be used to select translations to global calls to gettext() and ngettext() everywhere in python. .. note:: If this method returns None then all i18n services are disabled. """ try: return self.gettext_domain except AttributeError: pass def get_locale_dir(self): """ Get the path of the gettext translation catalogs for this command. This value is used to bind the domain returned by :meth:`get_gettext_domain()` to a specific directory. .. note:: If this method returns None then standard, system-wide locations are used (on compatibles systems). In practical terms, on Windows, you may need to use it to have access to localization data. """ try: return self.locale_dir except AttributeError: pass def get_sub_commands(self): """ Get a list of sub-commands of this command. :returns: ``self.sub_commands``, if defined. This is a sequence of pairs ``(name, cls)`` where ``name`` is the name of the sub command and ``cls`` is a command class (not an object). The ``name`` can be None if the command has a version of :meth:`get_cmd_name()` that returns an useful value. :returns: An empty tuple otherwise Applications can create hierarchical commands by defining the ``sub_commands`` attribute. Many developers are familiar with nested commands, for example ``git commit`` is a sub-command of the ``git`` command. All commands can be nested this way. """ try: return self.sub_commands except AttributeError: return () def get_cmd_spices(self): """ Get a list of spices requested by this command. Feature flags are a mechanism that allows application developers to control ingredients (switch them on or off) as well as to control how some ingredients behave. :returns: ``self.spices``, if defined. This should be a set of strings. Each string represents as single flag. Ingredients should document the set of flags they understand and use. :returns: An empty set otherwise Some flags have a generic meaning, you can scope a flag to a given ingredient using the ``name:`` prefix where the name is the name of the ingredient. """ try: spices = self.spices except AttributeError: spices = set() return spices def main(self, argv=None, exit=True): """ Shortcut for running a command. See :meth:`guacamole.recipes.Recipe.main()` for details. """ return CommandRecipe(self).main(argv, exit) def get_localized_docstring(obj, domain): """Get a cleaned-up, localized copy of docstring of this class.""" if obj.__class__.__doc__ is not None: return inspect.cleandoc( gettext.dgettext(domain, obj.__class__.__doc__)) class CommandRecipe(Recipe): """A recipe for using commands.""" def __init__(self, command): """Initialize a recipe for working with a specific command.""" self.command = command def get_ingredients(self): """Get a list of ingredients for guacamole.""" return [ ansi.ANSIIngredient(), cmdtree.CommandTreeBuilder(self.command), cmdtree.CommandTreeDispatcher(), argparse.AutocompleteIngredient(), argparse.ParserIngredient(), crash.VerboseCrashHandler(), ] guacamole-0.9.2/guacamole/recipes/__init__.py0000664000175000017500000001221612532100726021127 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """ APIs for guacamole add-on developers. This module contains the public APIs for add-on developers. Add-ons (or plug-ins) for guacamole are called **ingredients**. The :class:`Ingredient` class contains a description of available add-on methods. Ingredients are somewhat similar to Django middleware as they can influence the execution of an application across its life-cycle. All of core guacamole features are implemented as ingredients. Developers are encouraged to read core ingredients to understand how to formulate their own design. Ingredient APIs are *public*. They will be maintained for backwards compatibility. Since Guacamole doesn't automatically enable any third-party ingredients, application developers that wish to use them need to use the :mod:`guacamole.core` module to create their own guacamole out of available ingredients. Ingredient developers are recommended in documenting how to use each ingredient this way. In addition this module contains the public APIs for creating custom mixes of guacamole. A custom mix begins with a :class:`~guacamole.core.Bowl` with any number of :class:`~guacamole.core.Ingredient` objects added. If you are familiar with the :class:`~guacamole.recipes.cmd.Command` class you should know that they are using the recipe system internally. They refer to pre-made recipes that put particular ingredients into the bowl for a ready dish. If you wish to build a custom experience on top of guacamole, please provide a new recipe class. Recipes are how applications should interact with any guacamole mixtures. """ from __future__ import absolute_import, print_function, unicode_literals from guacamole.core import Bowl __all__ = ( 'Recipe', 'RecipeError', ) class Recipe(object): """Mechanism to use ingredients to dispatch and invoke commands.""" def get_ingredients(self): """ Get a list of ingredients for making guacamole. :returns: A list of initialized ingredients. :raises RecipeError: If the recipe is wrong. This is a developer error. Do not handle this exception. Consult the error message to understand what the problem is and correct the recipe instead. """ def prepare(self): """ Prepare a bowl with the ingredients specified by this recipe. :return: A new :class:`Bowl` instance with all the ingredients prepared. """ return Bowl(self.get_ingredients()) def main(self, argv=None, exit=True): """ Shortcut to prepare a bowl of guacamole and eat it. :param argv: Command line arguments or None. None means that sys.argv is used :param exit: Raise SystemExit after finishing execution :returns: Whatever is returned by the eating the guacamole. :raises: Whatever is raised by eating the guacamole. .. note:: This method always either raises and exception or returns an object. The way it behaves depends on the value of the `exit` argument. This method can be used to quickly take a recipe, prepare the guacamole and eat it. It is named main as it is applicable as the main method of an application. The `exit` argument controls if main returns normally or raises SystemExit. By default it will raise SystemExit (it will either wrap the return value with SystemExit or re-raise the SystemExit exception again). If SystemExit is raised but `exit` is False the argument to SystemExit is unwrapped and returned instead. """ bowl = self.prepare() try: retval = bowl.eat(argv) except SystemExit as exc: if exit: raise else: return exc.args[0] else: if retval is None: retval = 0 if exit: raise SystemExit(retval) else: return retval class RecipeError(Exception): """ Exception raised when the recipe for guacamole is incorrect. This exception is only used when a set of ingredients is ordered correctly or has some missing elements. Each time this exception is raised it is accompanied by a detailed message that should help you to resolve the problem. .. note:: This exception should not be handled, it is a developer error. """ guacamole-0.9.2/guacamole/test_core.py0000664000175000017500000000243512532100726017727 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Tests for guacamole core.""" from __future__ import absolute_import, print_function, unicode_literals import unittest from guacamole.core import Bowl class TestBowl(unittest.TestCase): """Tests for the Bowl class.""" def setUp(self): """Common initialization code.""" self.bowl = Bowl([]) def test_spices(self): """Bowl.add_spice() and Bowl.has_spice() work as expected.""" self.assertFalse(self.bowl.has_spice("salt")) self.bowl.add_spice('salt') self.assertTrue(self.bowl.has_spice("salt")) guacamole-0.9.2/guacamole/ingredients/0000775000175000017500000000000012560714745017712 5ustar zygazyga00000000000000guacamole-0.9.2/guacamole/ingredients/test_cmdtree.py0000664000175000017500000000403612532100726022734 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Tests for the cmdtree module.""" from __future__ import absolute_import, print_function, unicode_literals import unittest from guacamole.core import Bowl from guacamole.ingredients.cmdtree import CommandTreeBuilder from guacamole.recipes.cmd import Command class _sub(Command): spices = ('mustard',) class _cmd(Command): spices = ('salt', 'pepper') sub_commands = (('sub', _sub),) class CommandTreeBuilderTests(unittest.TestCase): """Tests for the CommandTreeBuilder class.""" def setUp(self): """Common initialization method.""" self.bowl = Bowl([CommandTreeBuilder(_cmd())]) self.bowl.eat() def test_build_command_tree(self): """check if a correct command tree is built.""" cmd_obj = self.bowl.context.cmd_tree[1] sub_obj = self.bowl.context.cmd_tree[2][0][1] self.assertIsInstance(cmd_obj, _cmd) self.assertIsInstance(sub_obj, _sub) self.assertEqual( self.bowl.context.cmd_tree, (None, cmd_obj, (('sub', sub_obj, ()),))) def test_collect_spices(self): """check if spices are collected from top-level command only.""" self.assertTrue(self.bowl.has_spice('salt')) self.assertTrue(self.bowl.has_spice('pepper')) self.assertFalse(self.bowl.has_spice('mustard')) guacamole-0.9.2/guacamole/ingredients/cmdtree.py0000664000175000017500000001774412532100726021707 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Ingredient for arranging commands into a tree structure.""" from __future__ import absolute_import, print_function, unicode_literals import collections import logging import types from guacamole.core import Ingredient _logger = logging.getLogger("guacamole") #: A named tuple for representing the hierarchy of commands. # # The ``cmd_obj`` field is an instance of a Command class. # The ``cmd_name`` field is the effective name of the command. # The ``children`` field is a tuple of cmd_tree_node tuples. cmd_tree_node = collections.namedtuple( 'cmd_tree_node', 'cmd_name cmd_obj children') class CommandTreeBuilder(Ingredient): """ Ingredient for arranging commands into a tree of instances. Since commands and sub-commands are specified as classes there has to be an ingredient that instantiates them and resolves all the naming ambiguities. Here it is. This component acts early, in its :meth:`added()` method. """ def __init__(self, command): """ Initialize the ingredient with a given top-level command. :param command: The command that is the top of a commad hierarchy. """ self.command = command def added(self, context): """ Ingredient method called before anything else. Here this method just builds the full command tree and stores it inside the context as the ``cmd_tree`` attribute. The structure of the tree is explained by the :func:`build_cmd_tree()` function. """ context.cmd_tree = self._build_cmd_tree(self.command) context.cmd_toplevel = context.cmd_tree.cmd_obj # Collect spices from the top-level command for spice in context.cmd_toplevel.get_cmd_spices(): context.bowl.add_spice(spice) def _build_cmd_tree(self, cmd_cls, cmd_name=None): """ Build a tree of commands. :param cmd_cls: The Command class or object to start with. :param cmd_name: Hard-coded name of the command (can be None for auto-detection) :returns: A tree structure represented as tuple ``(cmd_obj, cmd_name, children)`` Where ``cmd_obj`` is a Command instance, cmd_name is its name, if any (it might be None) and ``children`` is a tuple of identical tuples. Note that command name auto-detection relies on :meth:`guacamole.recipes.cmd.Command.get_cmd_name()`. Let's look at a simple git-like example:: >>> from guacamole import Command >>> class git_log(Command): >>> pass >>> class git_stash_list(Command): >>> pass >>> class git_stash(Command): >>> sub_commands = (('list', git_stash_list),) >>> class git(Command): >>> sub_commands = (('log', git_log), >>> ('stash', git_stash)) >>> build_cmd_tree(git) (None, '', ( ('log', , ()), ('stash', , ( ('list', , ()),),),),) """ if isinstance(cmd_cls, type): cmd_obj = cmd_cls() else: cmd_obj = cmd_cls if cmd_name is None: cmd_name = cmd_obj.get_cmd_name() return cmd_tree_node(cmd_name, cmd_obj, tuple([ self._build_cmd_tree(subcmd_cls, subcmd_name) for subcmd_name, subcmd_cls in cmd_obj.get_sub_commands()])) class CommandTreeDispatcher(Ingredient): """ Ingredient for dispatching commands hierarchically. This ingredient builds on the :class:`CommandTreeBuilder` ingredient. It implements the :meth:`dispatch()` method that recurses from the top (root) of the command tree down to the appropriate leaf, calling the invoke() method of each command. The process stops on the first command that returns a value other than None, raises an exception or until a leaf command is reached. THe ability to return early allows commands to perform some sanity checks or short- circuit execution that is hard to express using standard parser APIs. Lastly, a command can return a generator, this is treated as a sign that the generator implements a context-manager-like API. In this case the generator is called exactly twice and can be used to manage resources during the lifetime of all sub-commands. """ def dispatch(self, context): """Dispatch execution to the invoke() method of selected commands.""" return self._dispatch(context, 0) def _dispatch(self, context, level): # Find the command we're about to execute. try: command = getattr(context.args, 'command{}'.format(level)) except AttributeError: return else: from guacamole.recipes.cmd import Command assert isinstance(command, Command) # Invoke the command we found, if any. _logger.debug("Invoking command %r", command) retval = command.invoked(context) # Interpret the return value to know what to do next if isinstance(retval, types.GeneratorType): # Generators are invoked "around" sub-commands. # This allows them to use context managers and prepare # the execution environment for sub-commands reliably. _logger.debug("Command %r uses generator-based invoke. " "Invoking sub-commands (if any)", command) return self._dispatch_generator(context, level, retval, command) elif retval is None: # None is simply ignored and execution continues until a leaf # command is reached or until ... _logger.debug("Command %r returned None from invoke. " "Invoking sub-commands (if any)", command) return self._dispatch_None(context, level, retval, command) else: # ... or until a non-None result is produced. _logger.debug("Command %r returned code %s, returning", command, retval) return self._dispatch_other(context, level, retval, command) def _dispatch_generator(self, context, level, retval, command): # Generators are dispatched with two next() calls. # The first one is just there to start executing the code and reach # the (first and only) yield statement. next(retval) # Next, we dispatch the next sub-command. try: return self._dispatch(context, level + 1) finally: # Lastly, and this is done in a finally block to ensure it happens # in spite of exceptions being thrown. We call the generator again. try: next(retval) except StopIteration: pass else: _logger.error( "BUG in %s.invoke(). " "Each generator-based invoke() MUST use exactly " "one yield statement.", command.__class__.__name__) def _dispatch_None(self, context, level, retval, command): return self._dispatch(context, level + 1) def _dispatch_other(self, context, level, retval, command): return retval guacamole-0.9.2/guacamole/ingredients/argparse.py0000664000175000017500000002317112560712471022066 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """ Ingredients for using arparse for parsing command line arguments. This module contains two ingredients. The main one is the :class:`ParserIngredient`. It is responsible for handling all of the command line parsing and command argument registration. It is a part of the recipe for the command class. Note that command dispatch is not handled by this ingredient (see :class:`~guacamole.ingredients.cmdtree.CommandTreeIngredient`). The second ingredient is :class:`AutocompleteIngredient` which relies on the third-party argcomplete module to add support for automatic command line completion to supported shells (bash). """ from __future__ import absolute_import, print_function, unicode_literals import argparse from guacamole.core import Ingredient from guacamole.recipes import RecipeError # from guacamole._argparse import LegacyHelpFormatter class ParserIngredient(Ingredient): """ Ingredient for using argparse to parse command line arguments. This ingredient uses the following Ingredient methods: - ``build_early_parser()`` - ``preparse()`` - ``build_parser()`` - ``parse()`` The main parser is constructed in, unsurprisingly, the :meth:`build_parser()` method and stored in the context as ``parser``. Other ingredients can be added *after* the ``ParserIngredient`` and can extend the available arguments (on the root parser) by using standard argparse APIs such as ``parser.add_argument()`` or ``parser.add_argument_group()``. This parser is used to handle all of command line in the :meth:`parse()` method. While most users won't concern themselves with this design decision, there is also a second parser, called the *early parser*, that is used to *pre-parse* the command line arguments. This can be used as a way to optimize subsequent actions as, perhaps, knowing which commands are going to be invoked there will be no need to instantiate and prepare *all* of the commands in the command tree. Currently this feature is not used. To take advantage of this knowledge you can look at the ``context.early_args`` object which contains the result of parsing the command line with the *early parser*. The early parser is a simple parser consisting of ``--help``, ``--version`` (if applicable) and *rest*. The *rest* argument can be used as a hint as to what is coming next (e.g. if it matches a name of a command we know to exist) After parsing is done the results of parsing the command line are stored in the ``context.args`` attribute. This is commonly accessed by individual commands from their ``invoke()`` methods. """ def build_early_parser(self, context): """ Create the early argument parser. This method creates the early argparse argument parser. The early parser doesn't know about any of the sub-commands so it can be used much earlier during the start-up process (before commands are loaded and initialized). """ context.early_parser = self._create_early_parser(context) def preparse(self, context): """ Parse a portion of command line arguments with the early parser. This method relies on ``context.argv`` and ``context.early_parser`` and produces ``context.early_args``. The ``context.early_args`` object is the return value from argparse. It is the dict/object like namespace object. """ context.early_args, unused = ( context.early_parser.parse_known_args(context.argv)) def build_parser(self, context): """ Create the final argument parser. This method creates the non-early (full) argparse argument parser. Unlike the early counterpart it is expected to have knowledge of the full command tree. This method relies on ``context.cmd_tree`` and produces ``context.parser``. Other ingredients can interact with the parser up until :meth:`parse()` is called. """ context.parser, context.max_level = self._create_parser(context) def parse(self, context): """ Parse command line arguments. This method relies on ``context.argv`` and ``context.early_parser`` and produces ``context.args``. Note that ``.argv`` is modified by :meth:`preparse()` so it actually has _less_ things in it. The ``context.args`` object is the return value from argparse. It is the dict/object like namespace object. """ context.args = context.parser.parse_args(context.argv) def _create_parser(self, context): cmd_name, cmd_obj, cmd_subcmds = context.cmd_tree parser = argparse.ArgumentParser( prog=cmd_name, **self._get_parser_kwargs(cmd_obj)) parser.add_argument("-h", "--help", action="help") self._maybe_add_version(parser, cmd_obj) max_level = self._add_command_to_parser( parser, cmd_name, cmd_obj, cmd_subcmds) return parser, max_level def _create_early_parser(self, context): early_parser = argparse.ArgumentParser(add_help=False) early_parser.add_argument( "rest", nargs="...", help=argparse.SUPPRESS) early_parser.add_argument( "-h", "--help", action="store_const", const=None) cmd_name, cmd_obj, cmd_subcmds = context.cmd_tree version = cmd_obj.get_cmd_version() if version is not None: early_parser.add_argument( "--version", action="store_const", const=None) return early_parser def _maybe_add_version(self, parser, command): version = command.get_cmd_version() if version is not None: # NOTE: help= is provided explicitly as argparse doesn't wrap # everything with _() correctly (depending on version) parser.add_argument( "--version", action="version", version=version, help="show program's version number and exit") def _get_parser_kwargs(self, command): return { 'usage': command.get_cmd_usage(), 'description': command.get_cmd_description(), 'epilog': command.get_cmd_epilog(), 'add_help': False, # formatter_class=LegacyHelpFormatter, } def _add_command_to_parser( self, parser, cmd_name, cmd_obj, cmd_subcmds, level=0 ): # Register this command cmd_obj.register_arguments(parser) parser.set_defaults(**{'command{}'.format(level): cmd_obj}) # Register sub-commands of this command (recursively) if not cmd_subcmds: return level subparsers = parser.add_subparsers( help="sub-command to pick") max_level = level for subcmd_name, subcmd_obj, subcmd_cmds in cmd_subcmds: sub_parser = subparsers.add_parser( subcmd_name, help=subcmd_obj.get_cmd_help(), **self._get_parser_kwargs(subcmd_obj)) sub_parser.add_argument("-h", "--help", action="help") max_level = max( max_level, self._add_command_to_parser( sub_parser, subcmd_name, subcmd_obj, subcmd_cmds, level + 1)) return max_level class AutocompleteIngredient(Ingredient): """ Ingredient for adding shell auto-completion. .. warning:: This component is not widely tested due to difficulty of providing actual integration. It might be totally broken. .. note:: To effectively get tab completion you need to have the ``argcomplete`` package installed. In addition, a per-command initialization command has to be created and sourced by the shell. Look at argcomplete documentation for details. """ def parse(self, context): """ Optionally trigger argument completion in the invoking shell. This method is called to see if bash argument completion is requested and to honor the request, if needed. This causes the process to exit (early) without giving other ingredients a chance to initialize or shut down. Due to the way argcomple works, no other ingredient can print() anything to stdout prior to this point. """ try: import argcomplete except ImportError: return try: parser = context.parser except AttributeError: raise RecipeError( """ The context doesn't have the parser attribute. The auto-complete ingredient depends on having a parser object to generate completion data for she shell. In a typical application this requires that the AutocompleteIngredient and ParserIngredient are present and that the auto-complete ingredient precedes the parser. """) else: argcomplete.autocomplete(parser) guacamole-0.9.2/guacamole/ingredients/test_ansi.py0000664000175000017500000000344312560711136022250 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Tests for the ansi module.""" from __future__ import absolute_import, print_function, unicode_literals import io import sys import unittest if sys.version_info[:2] <= (3, 3): import mock else: from unittest import mock from guacamole.ingredients.ansi import ANSIFormatter class ANSIFormatterTests(unittest.TestCase): """Tests for the ANSIFormatter class.""" def test_flush_works(self): """check that aprint(..., flush=True) works okay.""" # https://github.com/zyga/guacamole/issues/9 # This should print to our stream stream = io.StringIO() fmt = ANSIFormatter(enabled=False) fmt.aprint("hello world", file=stream, flush=True) self.assertEqual(stream.getvalue(), "hello world\n") # This should print to sys.stdout with mock.patch('sys.stdout', spec_set=True) as mocked_stdout: fmt.aprint("goodbye world", file=None, flush=True) mocked_stdout.write.assert_has_calls([ mock.call("goodbye world"), mock.call("\n"), ]) guacamole-0.9.2/guacamole/ingredients/__init__.py0000664000175000017500000000155212522110401021777 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Package with ingredients bundled with guacamole.""" from __future__ import absolute_import, print_function, unicode_literals guacamole-0.9.2/guacamole/ingredients/ansi.py0000664000175000017500000004223712560714345021222 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Ingredients for using ANSI command sequences.""" from __future__ import absolute_import, print_function, unicode_literals import sys from guacamole.core import Ingredient class ANSI(object): """ Numerous ANSI constants. .. seealso:: Original specification in the `Standard ECMA 48 `_, page 61 (75th page of the PDF). Wikipedia article about `ANSI escape code `_. .. attribute:: cmd_erase_display Command for erasing the whole display .. attribute:: cmd_erase_line Command for erasing the current line .. attribute:: cmd_sgr_reset_all: Command for resetting all SGR attributes .. attribute:: sgr_reset_all: SGR code for resetting all attributes .. attribute:: sgr_bold: Causes text to be rendered with bold face font or, alternatively, to be rendered with bright color variant. This code is widely supported on Linux. It is not supported on Windows. .. attribute:: sgr_bright: Alternate spelling of :attr:`sgr_bold`. .. attribute:: sgr_faint: SGR code that activates faint color subset .. attribute:: srg_dim: Alternate spelling of ``sgr_faint`` .. attribute:: srg_italic: SGR code that activates italic font face .. attribute:: sgr_underline: SGR code that activates underline mode .. attribute:: sgr_blink_slow: SGR code that activates slow blinking of characters .. attribute:: sgr_blink_fast: SGR code that activates fast blinking of characters .. attribute:: sgr_reverse: SGR code that activates reverse-video mode .. attribute:: sgr_double_underline: SGR code that activates double-underline mode """ cmd_erase_display = '\033[2J' cmd_erase_line = '\033[K' cmd_sgr_reset_all = '\033[0m' @staticmethod def cmd_sgr(sgr_list): """Get a SGR (Set Graphics Rendition) code.""" return '\033[{}m'.format(';'.join(sgr_list)) # SGR 0-9: text attribute control sgr_reset_all = '0' sgr_bold = '1' sgr_bright = '1' sgr_faint = sgr_dim = '2' sgr_italic = '3' sgr_underline = '4' sgr_blink_slow = '5' sgr_blink_fast = '6' sgr_reverse = '7' sgr_concealed = '8' sgr_crossed = '9' # SGR 10-20: font set control (not implemented) sgr_font_default = '10' sgr_font_alt1 = '11' sgr_font_alt2 = '12' sgr_font_alt3 = '13' sgr_font_alt4 = '14' sgr_font_alt5 = '15' sgr_font_alt6 = '16' sgr_font_alt7 = '17' sgr_font_alt8 = '18' sgr_font_alt9 = '19' sgr_font_fraktur = '20' # SGR 21-29: text attribute control (cont.) sgr_double_underline = '21' sgr_normal = '22' # undo sgr_bold and sgr_dim sgr_not_italic = '23' # also undoes Fraktur sgr_not_underline = '24' sgr_steady = '25' # undo sgr_blink_{slow,fast} # 26 - reserved for proportional spacing sgr_positive = '27' # undo sgr_reverse sgr_reveal = '28' # undo sgr_concealed sgr_not_crossed = '29' # undo sgr_crossed # SGR 30-39: foreground color control sgr_fg_black = '30' sgr_fg_red = '31' sgr_fg_green = '32' sgr_fg_yellow = '33' sgr_fg_blue = '34' sgr_fg_magenta = '35' sgr_fg_cyan = '36' sgr_fg_white = '37' @staticmethod def sgr_fg_rgb(r, g, b): """Get SGR (Set Graphics Rendition) foreground RGB color.""" return '38;2;{};{};{}'.format(r, g, b) @staticmethod def sgr_fg_indexed(i): """Get SGR (Set Graphics Rendition) foreground indexed color.""" return '38;5;{}'.format(i) sgr_fg_default = '39' # SGR 40-49: background color control sgr_bg_black = '40' sgr_bg_red = '41' sgr_bg_green = '42' sgr_bg_yellow = '43' sgr_bg_blue = '44' sgr_bg_magenta = '45' sgr_bg_cyan = '46' sgr_bg_white = '47' @staticmethod def sgr_bg_rgb(r, g, b): """Get SGR (Set Graphics Rendition) background RGB color.""" return '48;2;{};{};{}'.format(r, g, b) @staticmethod def sgr_bg_indexed(i): """Get SGR (Set Graphics Rendition) background indexed color.""" return '48;5;{}'.format(i) sgr_bg_default = '49' # SGR 90-97: high-intensity foreground color control sgr_fg_bright_black = '90' sgr_fg_bright_red = '91' sgr_fg_bright_green = '92' sgr_fg_bright_yellow = '93' sgr_fg_bright_blue = '94' sgr_fg_bright_magenta = '95' sgr_fg_bright_cyan = '96' sgr_fg_bright_white = '97' # SGR 100-107: high-intensity background color control sgr_bg_bright_black = '100' sgr_bg_bright_red = '101' sgr_bg_bright_green = '102' sgr_bg_bright_yellow = '103' sgr_bg_bright_blue = '104' sgr_bg_bright_magenta = '105' sgr_bg_bright_cyan = '106' sgr_bg_bright_white = '107' def ansi_cmd(cmd, *args): """Get ANSI command code by name.""" try: obj = getattr(ANSI, str('cmd_{}'.format(cmd))) except AttributeError: raise ValueError( "incorrect command: {!r}".format(cmd)) if isinstance(obj, type("")): return obj else: return obj(*args) class _Visible: black = str('white') red = str('black') green = str('black') yellow = str('black') blue = str('black') magenta = str('black') cyan = str('black') white = str('black') bright_black = str('bright_white') bright_red = str('bright_black') bright_green = str('bright_black') bright_yellow = str('bright_black') bright_blue = str('bright_black') bright_magenta = str('bright_black') bright_cyan = str('bright_black') bright_white = str('bright_black') default = str('default') def get_visible_color(color): """Get the visible counter-color.""" if isinstance(color, (str, type(""))): try: return getattr(_Visible, str('{}'.format(color))) except AttributeError: raise ValueError("incorrect color: {!r}".format(color)) elif isinstance(color, tuple): return (0x80 ^ color[0], 0x80 ^ color[1], 0x80 ^ color[2]) elif isinstance(color, int): if 0 <= color <= 0x07: index = color return 0xFF if index == 0 else 0xE8 elif 0x08 <= color <= 0x0F: index = color - 0x08 return 0xFF if index == 0 else 0xE8 elif 0x10 <= color <= 0xE7: index = color - 0x10 if 0 <= index % 36 < 18: return 0xFF else: return 0x10 elif 0xE8 <= color <= 0xFF: index = color - 0x0E8 return 0xFF if 0 <= index < 12 else 0xE8 else: raise ValueError("incorrect color: {!r}".format(color)) def get_intensity(r, g, b): """Get the gray level intensity of the given rgb triplet.""" return int(round(255 * (0.3 * r + 0.59 * g + 0.11 * b))) def ansi_sgr(text, fg=None, bg=None, style=None, reset=True, **sgr): """ Apply desired SGR commands to given text. :param text: Text or anything convertible to text :param fg: (optional) Foreground color. Choose one of ``black``, ``red``, ``green``, ``yellow``, ``blue``, ``magenta`` ``cyan`` or ``white``. Note that the ``bright`` *SGR* impacts effective color in most implementations. """ # Ensure that text is really a string text = str(text) # NOTE: SGR stands for "set graphics rendition" sgr_list = [] # List of SGR codes # Load SGR code associated with desired foreground color if isinstance(fg, (str, type(""))): try: sgr_code = getattr(ANSI, str('sgr_fg_{}'.format(fg))) except AttributeError: raise ValueError("incorrect foreground color: {!r}".format(fg)) else: sgr_list.append(sgr_code) elif isinstance(fg, tuple): sgr_code = ANSI.sgr_fg_rgb(*fg) sgr_list.append(sgr_code) elif isinstance(fg, int): sgr_code = ANSI.sgr_fg_indexed(fg) sgr_list.append(sgr_code) elif fg is None: pass else: raise ValueError("incorrect foreground color: {!r}".format(fg)) # Load SGR code associated with desired background color if isinstance(bg, (str, type(""))): try: sgr_code = getattr(ANSI, str('sgr_bg_{}'.format(bg))) except AttributeError: raise ValueError("incorrect background color: {!r}".format(bg)) else: sgr_list.append(sgr_code) elif isinstance(bg, tuple): sgr_code = ANSI.sgr_bg_rgb(*bg) sgr_list.append(sgr_code) elif isinstance(bg, int): sgr_code = ANSI.sgr_bg_indexed(bg) sgr_list.append(sgr_code) elif bg is None: pass else: raise ValueError("incorrect background color: {!r}".format(bg)) # Load single SGR code for "style" if style is not None: try: sgr_code = getattr(ANSI, str('sgr_{}'.format(style))) except AttributeError: raise ValueError("incorrect text style: {!r}".format(style)) else: sgr_list.append(sgr_code) # Load additional SGR codes (custom) for name, active in sgr.items(): try: sgr_code = getattr(ANSI, str('sgr_{}'.format(name))) except AttributeError: raise ValueError("incorrect custom SGR code: {!r}".format(name)) else: if active: sgr_list.append(sgr_code) # Combine everything into one sequence if reset: return ANSI.cmd_sgr(sgr_list) + text + ANSI.cmd_sgr_reset_all else: return ANSI.cmd_sgr(sgr_list) + text class ANSIFormatter(object): """ Formatter for ANSI Set Graphics Rendition codes. An instance of this class is inserted into the context object as `ansi`. Using the fact that `ANSIFormatter` is callable one can easily add ANSI control sequences for foreground and background color as well as text attributes. """ def __init__(self, enabled=None): """ Initialize an ANSI Formatter. :param enabled: A tri-state that controls the formatter. If `enabled` is True or False then the obvious meaning is assumed. If `enabled` is None then the effective value is computed using ``sys.stdout.isatty()``. """ if enabled is None: enabled = sys.stdout.isatty() self._enabled = enabled @property def is_enabled(self): """ Flag indicating if text style is enabled. This property is useful to let applications customize their behavior if they know color support is desired and enabled. """ return self._enabled def cmd(self, cmd, *args): """Get an ANSI control sequence, if the formatter is enabled.""" if self._enabled: return ansi_cmd(cmd, *args) else: return '' def __call__(self, text, fg=None, bg=None, style=None, reset=True, **sgr): """ Format given text with ANSI control codes. If the formatter is enabled this is a pass-through to :func:`ansi_sgr()`. Otherwise this is a no-op that returns ``text``. """ if fg == 'auto' and bg is not None: fg = get_visible_color(bg) elif bg == 'auto' and fg is not None: bg = get_visible_color(fg) if self._enabled: return ansi_sgr(text, fg, bg, style, reset, **sgr) else: return text available_colors = ( str('black'), str('red'), str('green'), str('blue'), str('magenta'), str('cyan'), str('white')) available_bright_colors = ( str('bright_black'), str('bright_red'), str('bright_green'), str('bright_blue'), str('bright_magenta'), str('bright_cyan'), str('bright_white')) available_styles = ( None, 'bold', 'dim', 'italic', 'underline', 'blink_slow', 'blink_fast', 'reverse', 'concealed', 'crossed' ) def _aprint2(self, *values, **kwargs): """ ANSI formatting-aware print(). This method is a version of print() (function) that understands additional ansi control parameters. :param value: The values to print, same as with ``print()`` :param sep: Separator between values, same as with ``print()`` :param end: Terminator of the line, same as with ``print()`` :param file: File to print to, same as with ``print()`` :param flush: Flag that controls stream flush behavior, same as with ``print()`` :param fg: Foreground color, same as with :meth:`__call__()`. :param bg: Background color, same as with :meth:`__call__()`. :param style: Text style, same as with :meth:`__call__()`. :param reset: Flag that controls if ANSI attributes are reset at the end, same as with :meth:`__call__()`. :param sgr: Additonal (custom) Set Graphics Rendition directives, same as with :meth:`__call__()`. .. note:: This implementation is intended for Python 2 """ sep = kwargs.pop(str('sep'), ' ') end = kwargs.pop(str('end'), '\n') file = kwargs.pop(str('file'), None) or sys.stdout flush = kwargs.pop(str('flush'), False) fg = kwargs.pop(str('fg'), None) bg = kwargs.pop(str('bg'), None) style = kwargs.pop(str('style'), None) reset = kwargs.pop(str('reset'), True) sgr = kwargs text = sep.join(str(value) for value in values) text = self(text, fg, bg, style, reset, **sgr) print(text, end=end, file=file) if flush: file.flush() def _aprint3(self, *values, **kwargs): """ ANSI formatting-aware print(). This method is a version of print() (function) that understands additional ansi control parameters. :param value: The values to print, same as with ``print()`` :param sep: Separator between values, same as with ``print()`` :param end: Terminator of the line, same as with ``print()`` :param file: File to print to, same as with ``print()`` :param flush: Flag that controls stream flush behavior, same as with ``print()`` :param fg: Foreground color, same as with :meth:`__call__()`. :param bg: Background color, same as with :meth:`__call__()`. :param style: Text style, same as with :meth:`__call__()`. :param reset: Flag that controls if ANSI attributes are reset at the end, same as with :meth:`__call__()`. :param sgr: Additonal (custom) Set Graphics Rendition directives, same as with :meth:`__call__()`. .. note:: This implementation only works on Python 3 """ sep = kwargs.pop('sep', ' ') end = kwargs.pop('end', '\n') file = kwargs.pop('file', None) or sys.stdout flush = kwargs.pop('flush', False) fg = kwargs.pop('fg', None) bg = kwargs.pop('bg', None) style = kwargs.pop('style', None) reset = kwargs.pop('reset', True) sgr = kwargs text = sep.join(str(value) for value in values) text = self(text, fg, bg, style, reset, **sgr) print(text, end=end, file=file) # NOTE: Don't use print(..., flush=flush) as that doesn't work on # Python 3.2. This was https://github.com/zyga/guacamole/issues/9 if flush: file.flush() if sys.version_info[0] == 2: aprint = _aprint2 else: aprint = _aprint3 class ANSIIngredient(Ingredient): """Ingredient for colorizing output.""" def __init__(self, enable=None): """ Initialize the ANSI ingredient. :param enable: Tri-state flag that controls if the embedded ANSI formatter should be enabled. See :meth:`ANSI.__init__()`. """ if sys.platform == 'win32': try: import colorama except ImportError: enable = False else: colorama.init() self._enable = enable def added(self, context): """Ingredient method called before anything else.""" context.ansi = ANSIFormatter(self._enable) context.aprint = context.ansi.aprint guacamole-0.9.2/guacamole/ingredients/crash.py0000664000175000017500000000276612532100726021362 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """Ingredient for reacting to application crashes.""" from __future__ import absolute_import, print_function, unicode_literals import traceback from guacamole.core import Ingredient class VerboseCrashHandler(Ingredient): """ Ingredient for reacting to crashes with a traceback. You can add this ingredient into your recipe to react to application crashes. It will simply print the exception, as stored in ``context.exc_type``, ``context.exc_value`` and ``context.traceback`` and raise SystemExit(1). """ def dispatch_failed(self, context): """Print the unhandled exception and exit the application.""" traceback.print_exception( context.exc_type, context.exc_value, context.traceback) raise SystemExit(1) guacamole-0.9.2/guacamole/__init__.py0000664000175000017500000000370412560714506017507 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """ Guacamole -- command line applications that suck less. Guacamole is a flexible, modular system for creating command line applications. Guacamole comes with built-in support for writing command line applications that integrate well with the running system. A short list of supported features (ingredients) includes: - handling flat and hierarchical commands - hassle-free crash detection - hassle-free logging - internationalization and localization The guacamole ingredient system allows for third party add-ons. Please read the add-on developer guide for details. .. note:: Guacamole supports Python 2.7 and Python 3.2, 3.4 and 3.5. Other versions are not tested extensively. Versions earlier than 2.7 are not supported and won't be. Applications that still need to support the end-of-life Python 2.x release series are encouraged to update to Python 2.7. Lower-level classes can be found in the :mod:`guacamole.core` and :mod:`guacamole.recipes` modules. Add-on developers should use those modules exclusively. All other APIs are considered private. """ from __future__ import absolute_import, print_function from guacamole.recipes.cmd import Command __all__ = ('Command',) __version__ = '0.9.2' guacamole-0.9.2/guacamole/core.py0000664000175000017500000002513312532100726016670 0ustar zygazyga00000000000000# encoding: utf-8 # This file is part of Guacamole. # # Copyright 2012-2015 Canonical Ltd. # Written by: # Zygmunt Krynicki # # Guacamole is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License version 3, # as published by the Free Software Foundation. # # Guacamole is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with Guacamole. If not, see . """ The essence of guacamole. This module defines the three essential core classes: :class:`Ingredient`, :class:`Bowl`, :class:`Context`. All of those have stable APIs. """ from __future__ import absolute_import, print_function, unicode_literals import logging import sys __all__ = ( 'Bowl', 'Context', 'Ingredient', ) _logger = logging.getLogger('guacamole') class Ingredient(object): """ Part of guacamole. Ingredients are a mechanism for inserting functionality into Guacamole. The sequence of calls to ingredient methods is as follows: - :meth:`added()` The added method is where an ingredient can advertise itself to other ingredients that it explicitly collaborates with. - :meth:`preparse()` The preparse method is where ingredients can have a peek at the command line arguments. This can serve to optimize further actions. Essentially guacamole allows applications to parse arguments twice and limit the actions needed to do that correctly to the essential minimum required. - :meth:`early_init()` The early initialization method can be used to do additional initialization. It can take advantage of the fact that the whole command line arguments are now known and may have been analyzed further by the preparse method. - :meth:`parse()` The parse method is where applications are expected to fully understand command line arguments. This method can abort subsequent execution if arguments are wrong in in some way. After parsing command line arguments the application should be ready for execution. - :meth:`late_init()` The late initialization method mimics the early initialization method but is called after parsing all of the command line arguments. Again, it can be used to prepare addiotional resources necessary for a given application. - :meth:`dispatch()` The dispatch method is where applications execute the bulk of their actions. Dispatching is typically done with one of the standard ingredients which will locate the appropriate method to call into the application. Depending on the outcome of the dispatch (if an exception is raised or not) one of :meth:`dispatch_succeeded()`` or :meth:`dispatch_failed()` is called. - :meth:`shutdown()` This is the last method called on all ingredients. Each of those methods is called with a context argument (:class:`Context:`). A context is a free-for-all environment where ingredients can pass data around. There is no name-spacing. Ingredients should advertise what they do with the context and what to expect. """ def __str__(self): """ Get the string representation of this ingredient. The string method just returns the class name. Since the ingredient is an implemenetation detail it does not have anything that applications should show to the user. """ return self.__class__.__name__ def added(self, context): """Ingredient method called before anything else.""" def build_early_parser(self, context): """Ingredient method called to build the early parser.""" def preparse(self, context): """Ingredient method called to pre-parse command line aruments.""" def early_init(self, context): """Ingredient method for early initialization.""" def build_parser(self, context): """Ingredient method called to build the full parser.""" def parse(self, context): """Ingredient method called to parse command line arguments.""" def late_init(self, context): """Ingredient method for late initialization.""" def dispatch(self, context): """ Ingredient method for dispatching (execution). .. note:: The first ingredient that implements this method and returns something other than None will stop command dispatch! """ def dispatch_succeeded(self, context): """Ingredient method called when dispatching is correct.""" def dispatch_failed(self, context): """Ingredient method called when dispatching fails.""" def shutdown(self, context): """Ingredient method called after all other methods.""" class Context(object): """ Context for making guacamole with ingredients. A context object is created and maintained throughout the life-cycle of an executing tool. A context is passed as argument to all ingredient methods. Since context has no fixed API anything can be stored and loaded. Particular ingredients document how they use the context object. """ def __repr__(self): """ Get a debugging string representation of the context. The debugging representation shows all of the *names* of objects added to the context by various ingredients. Since the actual object can have large and complex debugging representation containing that representation was considered as a step against understanding what is in the context. """ return "".format( ', '.join(sorted(self.__dict__.keys()))) class Bowl(object): """ A vessel for preparing guacamole out of ingredients. .. note:: Each Bowl is single-use. If you eat it you need to get another one as this one is dirty and cannot be reused. """ def __init__(self, ingredients): """Prepare a guacamole out of given ingredients.""" self.ingredients = ingredients self.context = Context() self.context.bowl = self self.context.spices = set() def add_spice(self, spice): """ Add a single spice the bowl. """ self.context.spices.add(spice) def has_spice(self, spice): """ Check if a given spice is being used. This method can be used to construct checks if an optional ingredient feature should be enabled or not. Spices are simply strings that describe optional features. """ return spice in self.context.spices def eat(self, argv=None): """ Eat the guacamole. :param argv: Command line arguments or None. None means that sys.argv is used :return: Whatever is returned by the first ingredient that agrees to perform the command dispatch. The eat method is called to run the application, as if it was invoked from command line directly. """ # The setup phase, here KeyboardInterrupt is a silent sign to exit the # application. Any error that happens here will result in a raw # backtrace being printed to the user. try: self.context.argv = argv self._added() self._build_early_parser() self._preparse() self._early_init() self._build_parser() self._parse() self._late_init() except KeyboardInterrupt: self._shutdown() return # The execution phase. Here we differentiate SystemExit from all other # exceptions. SystemExit is just re-raised as that's what any piece of # code can raise to ask to exit the currently running application. All # other exceptions are recorded in the context and the failure-path of # the dispatch is followed. In other case, when there are no # exceptions, the success-path is followed. In both cases, ingredients # are shut down. try: return self._dispatch() except SystemExit: raise except BaseException: (self.context.exc_type, self.context.exc_value, self.context.traceback) = sys.exc_info() self._dispatch_failed() else: self._dispatch_succeeded() finally: self._shutdown() def _added(self): """Run the added() method on all ingredients.""" for ingredient in self.ingredients: ingredient.added(self.context) def _build_early_parser(self): """Run build_early_parser() method on all ingredients.""" for ingredient in self.ingredients: ingredient.build_early_parser(self.context) def _preparse(self): """Run the peparse() method on all ingredients.""" for ingredient in self.ingredients: ingredient.preparse(self.context) def _early_init(self): """Run the early_init() method on all ingredients.""" for ingredient in self.ingredients: ingredient.early_init(self.context) def _build_parser(self): """Run build_parser() method on all ingredients.""" for ingredient in self.ingredients: ingredient.build_parser(self.context) def _parse(self): """Run the parse() method on all ingredients.""" for ingredient in self.ingredients: ingredient.parse(self.context) def _late_init(self): """Run the late_init() method on all ingredients.""" for ingredient in self.ingredients: ingredient.late_init(self.context) def _dispatch(self): """Run the dispatch() method on all ingredients.""" for ingredient in self.ingredients: result = ingredient.dispatch(self.context) if result is not None: return result def _dispatch_succeeded(self): """Run the dispatch_succeeded() method on all ingredients.""" for ingredient in self.ingredients: ingredient.dispatch_succeeded(self.context) def _dispatch_failed(self): """Run the dispatch_failed() method on all ingredients.""" for ingredient in self.ingredients: ingredient.dispatch_failed(self.context) def _shutdown(self): """Run the shutdown() method on all ingredients.""" for ingredient in self.ingredients: ingredient.shutdown(self.context) guacamole-0.9.2/MANIFEST.in0000664000175000017500000000041012522110401015144 0ustar zygazyga00000000000000include AUTHORS.rst include CONTRIBUTING.rst include HISTORY.rst include COPYING include COPYING.LESSER include README.rst include examples/*.py recursive-exclude * __pycache__ recursive-exclude * *.py[co] recursive-include docs *.rst conf.py Makefile make.bat guacamole-0.9.2/setup.cfg0000664000175000017500000000055712560714745015272 0ustar zygazyga00000000000000[wheel] universal = 1 [extract_messages] add_comments = TRANSLATORS charset = utf-8 copyright_holder = Canonical Ltd. msgid_bugs_address = me@zygoon.pl output_file = po/guacamole.pot input_dirs = guacamole, i18n-argparse no_location = 1 [compile_catalog] directory = po/ domain = guacamole statistics = 1 [egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 guacamole-0.9.2/guacamole.egg-info/0000775000175000017500000000000012560714745017071 5ustar zygazyga00000000000000guacamole-0.9.2/guacamole.egg-info/PKG-INFO0000664000175000017500000001106512560714744020170 0ustar zygazyga00000000000000Metadata-Version: 1.1 Name: guacamole Version: 0.9.2 Summary: Guacamole is an command line tool library for Python Home-page: https://github.com/zyga/guacamole Author: Zygmunt Krynicki Author-email: me@zygoon.pl License: LGPLv3 Description: ============================================================ Guacamole - Framework for Creating Command Line Applications ============================================================ .. image:: https://badge.fury.io/py/guacamole.png :target: http://badge.fury.io/py/guacamole .. image:: https://travis-ci.org/zyga/guacamole.png?branch=master :target: https://travis-ci.org/zyga/guacamole .. image:: https://pypip.in/d/guacamole/badge.png :target: https://pypi.python.org/pypi/guacamole Tools, done right ================= Guacamole is a LGPLv3 licensed toolkit for creating good command line applications. Guacamole that does the right things for you and makes writing applications easier. .. testsetup:: import guacamole .. doctest:: >>> class HelloWorld(guacamole.Command): ... """A simple hello-world application.""" ... def register_arguments(self, parser): ... parser.add_argument('name') ... def invoked(self, ctx): ... print("Hello {0}!".format(ctx.args.name)) Running it directly is as simple as calling ``main()``: .. doctest:: >>> HelloWorld().main(['Guacamole'], exit=False) Hello Guacamole! 0 What you didn't have to do is what matters: - configure the argument parser - define and setup application logging - initialize internationalization features - add debugging facilities - write a custom crash handler Features ======== * Free software: LGPLv3 license * Documentation: https://guacamole.readthedocs.org. * Create command classes and run them from command line. * Group commands to create complex tools. * Use recipes, ingredients and spices to customize behavior History ======= 0.9.2 (2015-08-06) ------------------ * Fix https://github.com/zyga/guacamole/issues/11 0.9.1 (2015-08-06) ------------------ * Fix https://github.com/zyga/guacamole/issues/9 0.9 (2015-05-11) ---------------- * Vastly improved documentation * Bugfixes and changes based on early feedback * New cmdtree module with two ingredients (for instantiating commands and for dispatching the invoked method) * Simplified argparse ingredient (for just handling parser) * Unit tests and doctests for some of the functionality 0.8 (2015-04-21) ---------------- * First release on PyPI. 2012-2015 --------- * Released on PyPI as a part of plainbox as ``plainbox.impl.clitools``, ``plainbox.impl.logging``, ``plainbox.i18n`` and ``plainbox.impl.secure.plugins``. Keywords: argparse cli tool command sub-command subcommand Platform: UNKNOWN Classifier: Development Status :: 3 - Alpha Classifier: Intended Audience :: Developers Classifier: Environment :: Console Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3) Classifier: Natural Language :: English Classifier: Natural Language :: Polish Classifier: Operating System :: MacOS :: MacOS X Classifier: Operating System :: Microsoft :: Windows :: Windows 7 Classifier: Operating System :: Microsoft :: Windows :: Windows XP Classifier: Operating System :: POSIX Classifier: Operating System :: POSIX :: Linux Classifier: Topic :: Software Development Classifier: Topic :: Software Development :: Libraries Classifier: Programming Language :: Python :: 2 Classifier: Programming Language :: Python :: 2.7 Classifier: Programming Language :: Python :: 3 Classifier: Programming Language :: Python :: 3.2 Classifier: Programming Language :: Python :: 3.3 Classifier: Programming Language :: Python :: 3.4 Classifier: Programming Language :: Python :: Implementation :: CPython Classifier: Programming Language :: Python :: Implementation :: PyPy guacamole-0.9.2/guacamole.egg-info/top_level.txt0000664000175000017500000000001212560714744021613 0ustar zygazyga00000000000000guacamole guacamole-0.9.2/guacamole.egg-info/dependency_links.txt0000664000175000017500000000000112560714744023136 0ustar zygazyga00000000000000 guacamole-0.9.2/guacamole.egg-info/pbr.json0000664000175000017500000000005712560707735020552 0ustar zygazyga00000000000000{"is_release": false, "git_version": "95e3a44"}guacamole-0.9.2/guacamole.egg-info/SOURCES.txt0000664000175000017500000000211512560714744020753 0ustar zygazyga00000000000000AUTHORS.rst CONTRIBUTING.rst COPYING COPYING.LESSER HISTORY.rst MANIFEST.in README.rst setup.cfg setup.py docs/Makefile docs/authors.rst docs/conf.py docs/contributing.rst docs/history.rst docs/index.rst docs/installation.rst docs/make.bat docs/readme.rst docs/reference.rst docs/ingredients/ansi.rst docs/ingredients/cmdtree.rst docs/ingredients/crash.rst docs/ingredients/index.rst docs/usage/concepts.rst docs/usage/index.rst docs/usage/philosophy.rst docs/usage/recipes.rst examples/adder.py examples/fake-git.py examples/hello-world.py examples/rainbow.py guacamole/__init__.py guacamole/core.py guacamole/test_core.py guacamole.egg-info/PKG-INFO guacamole.egg-info/SOURCES.txt guacamole.egg-info/dependency_links.txt guacamole.egg-info/pbr.json guacamole.egg-info/top_level.txt guacamole.egg-info/zip-safe guacamole/ingredients/__init__.py guacamole/ingredients/ansi.py guacamole/ingredients/argparse.py guacamole/ingredients/cmdtree.py guacamole/ingredients/crash.py guacamole/ingredients/test_ansi.py guacamole/ingredients/test_cmdtree.py guacamole/recipes/__init__.py guacamole/recipes/cmd.pyguacamole-0.9.2/guacamole.egg-info/zip-safe0000664000175000017500000000000112522111176020504 0ustar zygazyga00000000000000 guacamole-0.9.2/AUTHORS.rst0000664000175000017500000000025412522110401015273 0ustar zygazyga00000000000000======= Credits ======= Development Lead ---------------- * Zygmunt Krynicki Contributors ------------ None yet. Why not be the first?