commit aa25250d28d0ea3b1a7c5a688c573ee05ec40d33 Author: Richard Neumann Date: Sat Dec 19 23:38:07 2020 +0100 init diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a288f39 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +*.egg-info +*.pyc +*~ +.buildconfig +.eggs +.installed_files.txt +__pycache__ +build +dist diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..8aade6c --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,4 @@ +version: 2 + +python: + version: 3.8 diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..10b66ca --- /dev/null +++ b/.travis.yml @@ -0,0 +1,7 @@ +language: python +python: + - 3.8 + - 3.9 +script: + - "python setup.py install" + - pytest diff --git a/LICENSE.txt b/LICENSE.txt new file mode 100644 index 0000000..94a9ed0 --- /dev/null +++ b/LICENSE.txt @@ -0,0 +1,674 @@ + 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 +. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..00be291 --- /dev/null +++ b/Makefile @@ -0,0 +1,28 @@ +FILE_LIST = ./.installed_files.txt + +.PHONY: build clean install publish pull push uninstall + +build: + @ ./setup.py sdist bdist_wheel + +clean: + @ rm -Rf ./build ./dist + +default: | pull clean install + +install: + @ ./setup.py install --record $(FILE_LIST) + +publish: + @ twine upload dist/* + +pull: + @ git pull + +push: + @ git push + +pypi: | build publish clean + +uninstall: + @ while read FILE; do echo "Removing: $$FILE"; rm "$$FILE"; done < $(FILE_LIST) diff --git a/README.md b/README.md new file mode 100644 index 0000000..5c236e4 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# rcon +An [RCON protocol](https://developer.valvesoftware.com/wiki/Source_RCON_Protocol) client implementation. + +## Requirements +[![Build Status](https://travis-ci.com/conqp/rcon.svg?branch=master)](https://travis-ci.com/conqp/mcipc) +`mcipc` requires Python 3.8 or higher. + +## Documentation +[![Documentation Status](https://readthedocs.org/projects/rcon/badge/?version=latest)](https://rcon.readthedocs.io/en/latest/?badge=latest) +Documentation is available on [readthedocs](https://rcon.readthedocs.io/en/latest). + +## Installations + +Install mcipc from the [AUR](https://aur.archlinux.org/packages/python-rcon/) or via: + + pip install mcipc + +## Quick start +The `RCON` protocol is used to remotely control a game server, i.e. execute +commands on a game server and receive the respective results. + +```python +from rcon import Client + +with Client('127.0.0.1', 5000) as client: + client.login('mysecretpassword') # Perform initial login. + seed = client.seed # Get the server's seed. + players = client.players # Get the server's players info. + mansion = client.locate('Mansion') # Get the next mansion's location. + +print(seed) +print(players) +print(mansion) +``` + +## License +Copyright (C) 2018-2020 Richard Neumann + +rcon 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. + +rcon 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 rcon. If not, see . diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 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 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/bugs.rst b/docs/source/bugs.rst new file mode 100644 index 0000000..29bfdef --- /dev/null +++ b/docs/source/bugs.rst @@ -0,0 +1,4 @@ +Reporting bugs +============== + +If you found a bug or want to suggest a new feature to be added top `mcpipc`, please open an appropriate issue on `GitHub `_. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..c6eb52c --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,64 @@ +from os.path import abspath +from sys import path + +import sphinx_rtd_theme + +path.insert(0, abspath('../../')) + +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'rcon' +copyright = '2020, Richard Neumann' +author = 'Richard Neumann' + +# The full version, including alpha/beta/rc tags +release = '1.4.5' + + +# -- General configuration --------------------------------------------------- + +# 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_rtd_theme', + 'sphinx.ext.autodoc' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- 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 = 'sphinx_rtd_theme' + +# 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 = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..227460c --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,23 @@ +rcon - An RCON client library +============================= + +`rcon` is a Python 3 library, which provides a client to interact with RCON servers. +It therefor implements the `RCON `_ protocol. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + installation + usage + modules + bugs + license + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..49255c7 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,15 @@ +Installation +============ + +If you use `Arch Linux` or one of its derivatives, you can install `rcon` from the `AUR `_. +Otherwise you can install `rcon` via pip: + +.. code-block:: bash + + pip install rcon + + +Requirements +============ + +`rcon` requires Python 3.8 or higher. diff --git a/docs/source/license.rst b/docs/source/license.rst new file mode 100644 index 0000000..8d434ba --- /dev/null +++ b/docs/source/license.rst @@ -0,0 +1,700 @@ +License +======= + +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 . diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000..b28b3a6 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +rcon +==== + +.. toctree:: + :maxdepth: 4 + + rcon diff --git a/docs/source/rcon.rst b/docs/source/rcon.rst new file mode 100644 index 0000000..0e23737 --- /dev/null +++ b/docs/source/rcon.rst @@ -0,0 +1,61 @@ +rcon package +============ + +Submodules +---------- + +rcon.config module +------------------ + +.. automodule:: rcon.config + :members: + :undoc-members: + :show-inheritance: + +rcon.console module +------------------- + +.. automodule:: rcon.console + :members: + :undoc-members: + :show-inheritance: + +rcon.exceptions module +---------------------- + +.. automodule:: rcon.exceptions + :members: + :undoc-members: + :show-inheritance: + +rcon.proto module +----------------- + +.. automodule:: rcon.proto + :members: + :undoc-members: + :show-inheritance: + +rcon.rconclt module +------------------- + +.. automodule:: rcon.rconclt + :members: + :undoc-members: + :show-inheritance: + +rcon.rconshell module +--------------------- + +.. automodule:: rcon.rconshell + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: rcon + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..1c4c3c8 --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,66 @@ +Usage +===== +For usage in code, there is the class :py:class:`rcon.Client`. + +.. code-block:: python + + from rcon import Client + + with Client('127.0.0.1', 5000) as client: + client.login('mysecretpassword') # Perform initial login. + seed = client.seed # Get the server's seed. + players = client.players # Get the server's players info. + mansion = client.locate('Mansion') # Get the next mansion's location. + + print(seed) + print(players) + print(mansion) + +Configuration +------------- +`rconclt` servers can be configured in :file:`/etc/rcon.conf`. +The configuration file format is: + +.. code-block:: ini + + [] + host = + port = + passwd = + prompt = + +The :code:`passwd` and :code:`prompt` entries are optional. + +rconclt +------- +`rconclt` is an RCON client script to communicate with game servers via the RCON protocol using the shell. +To communicate with a server, run: + +.. code-block:: bash + + rconclt [options] [...] + +rconshell +--------- +`rconshell` is an interactive RCON console to interact with game servers via the RCON protocol. +To start a shell, run: + +.. code-block:: bash + + rconshell [server] [options] + +Handling connection timeouts. +----------------------------- +You can specify an optional :code:`timeout=` parameter on both `Query` and `RCON` clients. +If a timeout is reached during a connection attempt, it will raise a `socket.timeout `_ exception. +The following example will raise a connection timeout after 1.5 seconds: + +.. code-block:: python + + try: + with Client('127.0.0.1', 5000, timeout=1.5) as client: + + except socket.timeout as timeout: + + +.. _configuration: diff --git a/files/rconclt b/files/rconclt new file mode 100755 index 0000000..9f2bd8a --- /dev/null +++ b/files/rconclt @@ -0,0 +1,8 @@ +#! /usr/bin/env python3 +"""An RCON client.""" + +from rcon.rconclt import main + + +if __name__ == '__main__': + main() diff --git a/files/rconshell b/files/rconshell new file mode 100755 index 0000000..a2a554c --- /dev/null +++ b/files/rconshell @@ -0,0 +1,8 @@ +#! /usr/bin/env python3 +"""An interactive RCON shell.""" + +from rcon.rconshell import main + + +if __name__ == '__main__': + main() diff --git a/rcon/__init__.py b/rcon/__init__.py new file mode 100644 index 0000000..cef7e96 --- /dev/null +++ b/rcon/__init__.py @@ -0,0 +1,16 @@ +"""RCON client library.""" + +from rcon.console import rconcmd +from rcon.exceptions import InvalidConfig +from rcon.exceptions import RequestIdMismatch +from rcon.exceptions import WrongPassword +from rcon.proto import Client + + +__all__ = [ + 'InvalidConfig', + 'RequestIdMismatch', + 'WrongPassword', + 'Client', + 'rconcmd' +] diff --git a/rcon/config.py b/rcon/config.py new file mode 100644 index 0000000..6f11d5f --- /dev/null +++ b/rcon/config.py @@ -0,0 +1,71 @@ +"""RCON server configuration.""" + +from __future__ import annotations +from configparser import ConfigParser, SectionProxy +from logging import getLogger +from pathlib import Path +from typing import Dict, Iterator, NamedTuple, Tuple + +from rcon.exceptions import InvalidConfig + + +__all__ = ['servers'] + + +CONFIG = ConfigParser() +CONFIG_FILE = Path('/etc/rcon.conf') +LOGGER = getLogger('RCON Config') + + +class Config(NamedTuple): + """Represents server configuration.""" + + host: str + port: int + passwd: str = None + prompt: str = 'RCON> ' + + @classmethod + def from_string(cls, string: str) -> Config: + """Reads the credentials from the given string.""" + try: + host, port = string.split(':') + except ValueError: + raise InvalidConfig(f'Invalid socket: {string}.') from None + + try: + port = int(port) + except ValueError: + raise InvalidConfig(f'Not an integer: {port}.') from None + + try: + passwd, host = host.rsplit('@', maxsplit=1) + except ValueError: + passwd = None + + return cls(host, port, passwd) + + @classmethod + def from_config_section(cls, section: SectionProxy) -> Config: + """Creates a credentials tuple from + the respective config section. + """ + host = section['host'] + port = section.getint('port') + passwd = section.get('passwd') + prompt = section.get('prompt') + return cls(host, port, passwd, prompt) + + +def entries(config_parser: ConfigParser) -> Iterator[Tuple[str, Config]]: + """Yields entries.""" + + for section in config_parser.sections(): + yield (section, Config.from_config_section(config_parser[section])) + + +def servers() -> Dict[str, Config]: + """Returns a dictionary of servers.""" + + CONFIG.read(CONFIG_FILE) + return dict(entries(CONFIG)) diff --git a/rcon/console.py b/rcon/console.py new file mode 100644 index 0000000..ad6dbec --- /dev/null +++ b/rcon/console.py @@ -0,0 +1,144 @@ +"""An interactive console.""" + +from getpass import getpass +from typing import Union + +from rcon.config import Config +from rcon.exceptions import RequestIdMismatch, WrongPassword +from rcon.proto import Client + + +__all__ = ['rconcmd'] + + +EXIT_COMMANDS = {'exit', 'quit'} +MSG_QUERY_LATER = '\nOkay, I will ask again later.' +MSG_ABORTED = '\nAborted...' +MSG_LOGIN_ABORTED = '\nLogin aborted. Bye.' +MSG_EXIT = 'Bye.' +MSG_SESSION_TIMEOUT = 'Session timed out. Please login again.' +MSG_EXIT_USAGE = 'Usage: {} [].' + + +def read(prompt: str, typ: type = None) -> type: + """Reads input and converts it to the respective type.""" + + while True: + raw = input(prompt) + + if typ is not None: + try: + return typ(raw) + except (TypeError, ValueError): + print(f'Invalid {typ}: {raw}') + continue + + return raw + + +def read_or_none(prompt: str, typ: type = None) -> type: + """Reads the input and returns None on EOFError.""" + + try: + return read(prompt, typ=typ) + except EOFError: + print(MSG_QUERY_LATER) + return None + + +def login(client: Client, passwd: str) -> str: + """Performs a login.""" + + if passwd is None: + passwd = getpass('Password: ') + + logged_in = False + + while not logged_in: + try: + logged_in = client.login(passwd) + except WrongPassword: + print('Invalid password.') + passwd = getpass('Password: ') + + return passwd + + +def get_config(host: str, port: int, passwd: str, prompt: str) -> Config: + """Reads the necessary arguments.""" + + while any(item is None for item in (host, port, passwd, prompt)): + if host is None: + host = read_or_none('Host: ') + + if port is None: + port = read_or_none('Port: ', typ=int) + + if passwd is None: + passwd = read_or_none('Password: ') + + if prompt is None: + prompt = read_or_none('Prompt: ') + + return Config(host, port, passwd, prompt) + + +def exit(exit_code: Union[int, str] = 0) -> int: # pylint: disable=W0622 + """Exits the interactive shell via exit command.""" + + print(MSG_EXIT) + return int(exit_code) + + +def rconcmd(host: str, port: int, passwd: str, prompt: str) -> int: + """Initializes the console.""" + + try: + config = get_config(host, port, passwd, prompt) + except KeyboardInterrupt: + print(MSG_ABORTED) + return 1 + + with Client(config.host, config.port) as client: + try: + passwd = login(client, config.passwd) + except (EOFError, KeyboardInterrupt): + print(MSG_LOGIN_ABORTED) + return 1 + + while True: + try: + command = input(config.prompt) + except EOFError: + print(f'\n{MSG_EXIT}') + break + except KeyboardInterrupt: + print() + continue + + try: + command, *args = command.split() + except ValueError: + continue + + if command in EXIT_COMMANDS: + try: + return exit(*args) # pylint: disable=R1722 + except (TypeError, ValueError): + print(MSG_EXIT_USAGE.format(command)) + continue + + try: + result = client.run(command, *args) + except RequestIdMismatch: + print(MSG_SESSION_TIMEOUT) + + try: + passwd = login(client, passwd) + except (EOFError, KeyboardInterrupt): + print(MSG_LOGIN_ABORTED) + return 2 + + print(result) + + return 0 diff --git a/rcon/exceptions.py b/rcon/exceptions.py new file mode 100644 index 0000000..11c6f6a --- /dev/null +++ b/rcon/exceptions.py @@ -0,0 +1,22 @@ +"""RCON exceptions.""" + + +__all__ = ['InvalidConfig', 'RequestIdMismatch', 'WrongPassword'] + + +class InvalidConfig(ValueError): + """Indicates invalid credentials.""" + + +class RequestIdMismatch(Exception): + """Indicates that the sent and received request IDs do not match.""" + + def __init__(self, sent: int, received: int): + """Sets the sent and received request IDs.""" + super().__init__(sent, received) + self.sent = sent + self.received = received + + +class WrongPassword(Exception): + """Indicates a wrong RCON password.""" diff --git a/rcon/proto.py b/rcon/proto.py new file mode 100644 index 0000000..218994a --- /dev/null +++ b/rcon/proto.py @@ -0,0 +1,186 @@ +"""Low-level protocol stuff.""" + +from __future__ import annotations +from enum import Enum +from logging import getLogger +from random import randint +from socket import SOCK_STREAM, socket +from typing import NamedTuple + +from rcon.exceptions import RequestIdMismatch +from rcon.exceptions import WrongPassword + + +__all__ = [ + 'LittleEndianSignedInt32', + 'Type', + 'Packet', + 'Client', + 'random_request_id' +] + + +LOGGER = getLogger(__file__) +TERMINATOR = '\x00\x00' + + +def random_request_id() -> LittleEndianSignedInt32: + """Generates a random request ID.""" + + return LittleEndianSignedInt32(randint(0, LittleEndianSignedInt32.MAX)) + + +class LittleEndianSignedInt32(int): + """A little-endian, signed int32.""" + + MIN = -2_147_483_648 + MAX = 2_147_483_647 + + def __init__(self, *_): + """Checks the boundaries.""" + super().__init__() + + if not self.MIN <= self <= self.MAX: + raise ValueError('Signed int32 out of bounds:', self) + + def __bytes__(self): + """Returns the integer as signed little endian.""" + return self.to_bytes(4, 'little', signed=True) + + @classmethod + def from_bytes(cls, bytes_: bytes) -> LittleEndianSignedInt32: + """Creates the integer from the given bytes.""" + return super().from_bytes(bytes_, 'little', signed=True) + + +class Type(Enum): + """Available packet types.""" + + LOGIN = 3 + COMMAND = 2 + RESPONSE = 0 + + def __int__(self): + """Returns the actual integer value.""" + return self.value + + def __bytes__(self): + """Returns the integer value as little endian.""" + return int(self).to_bytes(4, 'little', signed=True) + + @classmethod + def from_bytes(cls, bytes_: bytes) -> Type: + """Creates a type from the given bytes.""" + return cls(int.from_bytes(bytes_, 'little', signed=True)) + + +class Packet(NamedTuple): + """An RCON packet.""" + + id: LittleEndianSignedInt32 + type: Type + payload: str + terminator: str = TERMINATOR + + def __bytes__(self): + """Returns the packet as bytes with prepended length.""" + payload = bytes(self.id) + payload += bytes(self.type) + payload += self.payload.encode() + payload += self.terminator.encode() + size = len(payload).to_bytes(4, 'little', signed=True) + return size + payload + + @classmethod + def from_bytes(cls, bytes_: bytes) -> Packet: + """Creates a packet from the respective bytes.""" + id_ = LittleEndianSignedInt32.from_bytes(bytes_[:4]) + type_ = Type.from_bytes(bytes_[4:8]) + payload = bytes_[8:-2].decode() + + if (terminator := bytes_[-2:].decode()) != TERMINATOR: + LOGGER.warning('Unexpected terminator: %s', terminator) + + return cls(id_, type_, payload, terminator) + + @classmethod + def from_args(cls, *args: str) -> Packet: + """Creates a command packet.""" + return cls(random_request_id(), Type.COMMAND, ' '.join(args)) + + @classmethod + def from_login(cls, passwd: str) -> Packet: + """Creates a login packet.""" + return cls(random_request_id(), Type.LOGIN, passwd) + + +class Client: + """An RCON client.""" + + __slots__ = ('_socket', 'host', 'port', 'timeout', 'passwd') + + def __init__(self, host: str, port: int, *, timeout: float = None, + passwd: str = None): + """Initializes the base client with the SOCK_STREAM socket type.""" + self._socket = socket(type=SOCK_STREAM) + self.host = host + self.port = port + self.timeout = timeout + self.passwd = passwd + + def __enter__(self): + """Attempts an auto-login if a password is set.""" + self._socket.__enter__() + self._socket.settimeout(self.timeout) + self._socket.connect((self.host, self.port)) + + if self.passwd is not None: + self.login(self.passwd) + + return self + + def __exit__(self, typ, value, traceback): + """Delegates to the underlying socket's exit method.""" + return self._socket.__exit__(typ, value, traceback) + + def communicate(self, packet: Packet) -> Packet: + """Sends and receives a packet.""" + self._socket.send(bytes(packet)) + header = self._socket.recv(4) + length = int.from_bytes(header, 'little') + payload = self._socket.recv(length) + response = Packet.from_bytes(payload) + + if response.id == packet.id: + return response + + raise RequestIdMismatch(packet.id, response.id) + + def login(self, passwd: str) -> bool: + """Performs a login.""" + packet = Packet.from_login(passwd) + + try: + self.communicate(packet) + except RequestIdMismatch as mismatch: + if mismatch.received == -1: + raise WrongPassword() from None + + raise + + return True + + def run(self, command: str, *arguments: str) -> str: + """Runs a command.""" + packet = Packet.from_args(command, *arguments) + + try: + response = self.communicate(packet) + except RequestIdMismatch: + if self.passwd is not None: # Re-authenticate and retry command. + self.login(self.passwd) + return self.run(command, *arguments) + + raise + + return response.payload diff --git a/rcon/rconclt.py b/rcon/rconclt.py new file mode 100644 index 0000000..5ee16e1 --- /dev/null +++ b/rcon/rconclt.py @@ -0,0 +1,86 @@ +"""RCON client CLI.""" + +from argparse import ArgumentParser, Namespace +from getpass import getpass +from logging import DEBUG, INFO, basicConfig, getLogger +from socket import timeout +from sys import exit # pylint: disable=W0622 +from typing import Tuple + +from rcon.exceptions import InvalidConfig +from rcon.config import Config, servers +from rcon.exceptions import RequestIdMismatch, WrongPassword +from rcon.proto import Client + + +__all__ = ['get_credentials', 'main'] + + +LOGGER = getLogger('rconclt') +LOG_FORMAT = '[%(levelname)s] %(name)s: %(message)s' + + +def get_args() -> Namespace: + """Parses and returns the CLI arguments.""" + + parser = ArgumentParser(description='A Minecraft RCON client.') + parser.add_argument('server', help='the server to connect to') + parser.add_argument('-t', '--timeout', type=float, metavar='seconds', + help='connection timeout in seconds') + parser.add_argument('-d', '--debug', action='store_true', + help='print additional debug information') + parser.add_argument('command', help='command to execute on the server') + parser.add_argument('argument', nargs='*', default=(), + help='arguments for the command') + return parser.parse_args() + + +def get_credentials(server: str) -> Tuple[str, int, str]: + """Get the credentials for a server from the respective server name.""" + + try: + host, port, passwd = Config.from_string(server) + except InvalidConfig: + try: + host, port, passwd = servers()[server] + except KeyError: + LOGGER.error('No such server: %s.', server) + exit(2) + + if passwd is None: + try: + passwd = getpass('Password: ') + except (KeyboardInterrupt, EOFError): + print() + LOGGER.error('Aborted by user.') + exit(1) + + return (host, port, passwd) + + +def main(): + """Runs the RCON client.""" + + args = get_args() + log_level = DEBUG if args.debug else INFO + basicConfig(level=log_level, format=LOG_FORMAT) + host, port, passwd = get_credentials(args.server) + + try: + with Client(host, port, timeout=args.timeout) as client: + client.login(passwd) + text = client.run(args.command, *args.argument) + except ConnectionRefusedError: + LOGGER.error('Connection refused.') + exit(3) + except timeout: + LOGGER.error('Connection timeout.') + exit(4) + except RequestIdMismatch: + LOGGER.error('Unexpected request ID mismatch.') + exit(5) + except WrongPassword: + LOGGER.error('Wrong password.') + exit(6) + else: + print(text, flush=True) diff --git a/rcon/rconshell.py b/rcon/rconshell.py new file mode 100644 index 0000000..d7ad2ca --- /dev/null +++ b/rcon/rconshell.py @@ -0,0 +1,49 @@ +"""An interactive RCON shell.""" + +from argparse import ArgumentParser, Namespace +from logging import INFO, basicConfig, getLogger +from socket import timeout +from sys import exit # pylint: disable=W0622 + +from rcon.rconclt import get_credentials +from rcon.console import rconcmd + + +__all__ = ['get_args', 'main'] + + +LOGGER = getLogger('rconshell') +LOG_FORMAT = '[%(levelname)s] %(name)s: %(message)s' + + +def get_args() -> Namespace: + """Parses and returns the CLI arguments.""" + + parser = ArgumentParser(description='An interactive RCON shell.') + parser.add_argument('server', nargs='?', help='the server to connect to') + parser.add_argument('-p', '--prompt', default='RCON> ', metavar='PS1', + help='the shell prompt') + return parser.parse_args() + + +def main(): + """Runs the RCON shell.""" + + args = get_args() + basicConfig(level=INFO, format=LOG_FORMAT) + + if server := args.server: + host, port, passwd = get_credentials(server) + else: + host = port = passwd = None + + try: + exit_code = rconcmd(host, port, passwd, args.prompt) + except ConnectionRefusedError: + LOGGER.error('Connection refused.') + exit(3) + except timeout: + LOGGER.error('Connection timeout.') + exit(4) + + exit(exit_code) diff --git a/setup.py b/setup.py new file mode 100755 index 0000000..1bbc5f4 --- /dev/null +++ b/setup.py @@ -0,0 +1,21 @@ +#! /usr/bin/env python +"""Installation script.""" + +from setuptools import setup + +setup( + name='rcon', + version_format='{tag}', + setup_requires=['setuptools-git-version'], + author='Richard Neumann', + author_email='mail@richard-neumann.de', + python_requires='>=3.8', + packages=['rcon'], + scripts=['files/rconclt', 'files/rconshell'], + url='https://github.com/conqp/rcon', + license='GPLv3', + description='A RCON client library library.', + long_description=open('README.md').read(), + long_description_content_type="text/markdown", + keywords='python rcon client' +)