mctools


Namemctools JSON
Version 1.1.0 PyPI version JSON
download
home_pagehttps://github.com/Owen-Cochell/mctools
SummaryPython implementations of common Minecraft protocols.
upload_time2020-09-09 15:29:47
maintainer
docs_urlNone
authorOwen Cochell
requires_python>=3.6, <4
license
keywords minecraft rcon query ping server list ping
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Minecraft Connection Tools
A python implementation for interacting with Minecraft servers.

[![Documentation Status](https://readthedocs.org/projects/mctools/badge/?version=latest)](https://mctools.readthedocs.io/en/latest/?badge=latest)

# Introduction

mctools allows you to interact with Minecraft servers via [rcon](https://wiki.vg/RCON), 
[query](https://wiki.vg/Query), and [server list ping protocol](https://wiki.vg/Server_List_Ping).

This allows you to do the following:

 - Send and receive Minecraft server commands
 - Get player count(max and currently playing)
 - Get server version
 - Get the message of the day
 - Get currently installed plugins
 - And much more!

All of this can be achieved using simple, intuitive calls to mctools. mctools does all the heavy lifting for you!
Also, mctools has no external dependencies(Unless you are a windows user and need color support),
and only uses the python standard library. Just download and go!

# Example

Send a command to the Minecraft server via rcon:
```python
from mctools import RCONClient  # Import the RCONClient

HOST = 'mc.server.net'  # Hostname of the Minecraft server
PORT = 1234  # Port number of the RCON server

# Create the RCONClient:

rcon = RCONClient(HOST, port=PORT)

# Login to RCON:

if rcon.login("password"):

    # Send command to RCON - broadcast message to all players:

    resp = rcon.command("broadcast Hello RCON!")
```
 # Installation 

 You can install mctools via pip:

    $ pip install mctools

 If you are a windows user and want color support, then install mctools like so:

    $ pip install mctools[color]

 For more information on installing mctools, check out the instillation section in our 
 [documentation](https://mctools.readthedocs.io/en/latest/install.html).

 # Formatting

 mctools has support for handling Minecraft formatting codes. 
 You can decide weather mctools replaces formatting characters with intended values, removes them, or leaves them be.

 For example, lets say you received the following content during a rcon session:

    §e--------- §fHelp: Index (1/40) §e--------------------
    §7Use /help [n] to get page n of help.
    §6Aliases: §fLists command aliases
    §6Bukkit: §fAll commands for Bukkit
    §6ClearLag: §fAll commands for ClearLag
    §6Essentials: §fAll commands for Essentials
    §6LuckPerms: §fAll commands for LuckPerms
    §6Minecraft: §fAll commands for Minecraft
    §6Vault: §fAll commands for Vault
    §6WorldEdit: §fAll commands for WorldEdit

 As you can see, this text is somewhat hard to read. If you told mctools to remove the formatting characters, 
 then the output will look like this:

    --------- Help: Index (1/40) --------------------
    Use /help [n] to get page n of help.
    Aliases: Lists command aliases
    Bukkit: All commands for Bukkit
    ClearLag: All commands for ClearLag
    Essentials: All commands for Essentials
    LuckPerms: All commands for LuckPerms
    Minecraft: All commands for Minecraft
    Vault: All commands for Vault
    WorldEdit: All commands for WorldEdit

 Much easier to read and process. mctools handles this operation automatically, so you don't have to.
 mctools also handles situations where content is sent in ChatObject notation, and can extract messages from the 
 player sample list.

 To learn more about formatters, and how to create your own, 
 then please check out the [formatting documentation](https://mctools.readthedocs.io/en/latest/format.html).

 # MCLI - mctools Command Line Interface

 mctools is shipped with a CLI front end called mcli, which you can use to start rcon sessions, get stats
 via query/ping, check if a Minecraft server is up, ect. 

 After installing mctools(through pip or setuptools), you can invoke mcli like so:

    $ mcli --help

 You can also run mcli.py(which is located in the parent directory) if you downloaded the source code and did not
 install via pip/setuptools.

 The above command will generate the help menu for mcli. To learn more about mcli, please check out the 
 [mcli documentation](https://mctools.readthedocs.io/en/latest/mcli.html).

 # Documentation

 mctools has an extensive documentation. It contains tutorials, the API reference, and best practice recommendations.
 You can find the [documentation here](https://mctools.readthedocs.io/).

 Be sure to also check out the [mctools PyPi page](https://pypi.org/project/mctools/) for more information.

 # Contributing

 Pull requests are welcome and encouraged :) ! If you want to see a feature in mctools, a PR will be the quickest 
 way to get it included. Feel free to email me or open an issue if you have any problems.

 If you are interested in helping in the development of mctools, then send me an email, and we can get talking!
 Believe me, there is plenty of work that needs to be done. More help would be greatly appreciated!

 # Changelog

 ## 1.1.0

 This update adds some minor features and fixes some major bugs:

  ### Bug Fixes:

 - Fixed RCON packet fragmentation issue, mctools should now properly detect and handle RCON packet fragmentation
 - Fixed bug where PINGFormatter was looking for 'dark_grey' instead of 'dark_gray'
 - Fixed bug where ChatObjectFormatter did not properly parse ChatObjects
 - We now raise an exception if the RCON write data is too big, instead of leaving the connection in a unstable state

  ### Features Added:

 - Users can now specify the format method on a per-call basis
 - Users can change the timeout value after the object is instantiated
 - The RCON login check feature can be disabled, meaning that you can attempt to send packets
 even if you are not authenticated
 - Clients can now return raw packets
 - RCON now has custom exceptions

 This update is a prelude to another update I have working on.
 The next update will add numerous features, such as:

 - RCON Mixins for easing the process of getting/editing the following info:
   - Players connected
   - World Seed
   - Game Rules
   - Target Selectors
   - Many more...
 - Custom exceptions for Ping and Query
 - Even Better error handling
 - mcli RCON command/argument autocompletion
 - Custom datatypes for all operations
 - RCON SSH Forwarding support
 (You can technically do this as of now, but I want the library to invoke and handle this process) for a more
 secure RCON experience
 - Unit tests for mctools

 I have some of these complete as of now, but I wanted to push out the big bug fixes and minor stuff before 
 I finish creating and refining the features, as they may take me some time to implement.

 All of these features will be completely optional, and they will all be backwards compatible.
 So if you like the library as it is now, then you can completely ignore these new features.

 The documentation has been updated to reflect these changes.

 # Conclusion

 mctools offers a pythonic, reliable way to interact with Minecraft servers, without being too complicated.
 Please check the documentation for more information. More features (hopefully) coming soon!

 Thank you for reading!


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Owen-Cochell/mctools",
    "name": "mctools",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.6, <4",
    "maintainer_email": "",
    "keywords": "minecraft,rcon,query,ping,server list ping",
    "author": "Owen Cochell",
    "author_email": "owencochell@hotmail.com",
    "download_url": "https://files.pythonhosted.org/packages/06/36/6a39472d15f8f37ae7d0522c6f7c8b2d17e24fce854fc8cb375a773e53a5/mctools-1.1.0.tar.gz",
    "platform": "",
    "description": "# Minecraft Connection Tools\nA python implementation for interacting with Minecraft servers.\n\n[![Documentation Status](https://readthedocs.org/projects/mctools/badge/?version=latest)](https://mctools.readthedocs.io/en/latest/?badge=latest)\n\n# Introduction\n\nmctools allows you to interact with Minecraft servers via [rcon](https://wiki.vg/RCON), \n[query](https://wiki.vg/Query), and [server list ping protocol](https://wiki.vg/Server_List_Ping).\n\nThis allows you to do the following:\n\n - Send and receive Minecraft server commands\n - Get player count(max and currently playing)\n - Get server version\n - Get the message of the day\n - Get currently installed plugins\n - And much more!\n\nAll of this can be achieved using simple, intuitive calls to mctools. mctools does all the heavy lifting for you!\nAlso, mctools has no external dependencies(Unless you are a windows user and need color support),\nand only uses the python standard library. Just download and go!\n\n# Example\n\nSend a command to the Minecraft server via rcon:\n```python\nfrom mctools import RCONClient  # Import the RCONClient\n\nHOST = 'mc.server.net'  # Hostname of the Minecraft server\nPORT = 1234  # Port number of the RCON server\n\n# Create the RCONClient:\n\nrcon = RCONClient(HOST, port=PORT)\n\n# Login to RCON:\n\nif rcon.login(\"password\"):\n\n    # Send command to RCON - broadcast message to all players:\n\n    resp = rcon.command(\"broadcast Hello RCON!\")\n```\n # Installation \n\n You can install mctools via pip:\n\n    $ pip install mctools\n\n If you are a windows user and want color support, then install mctools like so:\n\n    $ pip install mctools[color]\n\n For more information on installing mctools, check out the instillation section in our \n [documentation](https://mctools.readthedocs.io/en/latest/install.html).\n\n # Formatting\n\n mctools has support for handling Minecraft formatting codes. \n You can decide weather mctools replaces formatting characters with intended values, removes them, or leaves them be.\n\n For example, lets say you received the following content during a rcon session:\n\n    \u00a7e--------- \u00a7fHelp: Index (1/40) \u00a7e--------------------\n    \u00a77Use /help [n] to get page n of help.\n    \u00a76Aliases: \u00a7fLists command aliases\n    \u00a76Bukkit: \u00a7fAll commands for Bukkit\n    \u00a76ClearLag: \u00a7fAll commands for ClearLag\n    \u00a76Essentials: \u00a7fAll commands for Essentials\n    \u00a76LuckPerms: \u00a7fAll commands for LuckPerms\n    \u00a76Minecraft: \u00a7fAll commands for Minecraft\n    \u00a76Vault: \u00a7fAll commands for Vault\n    \u00a76WorldEdit: \u00a7fAll commands for WorldEdit\n\n As you can see, this text is somewhat hard to read. If you told mctools to remove the formatting characters, \n then the output will look like this:\n\n    --------- Help: Index (1/40) --------------------\n    Use /help [n] to get page n of help.\n    Aliases: Lists command aliases\n    Bukkit: All commands for Bukkit\n    ClearLag: All commands for ClearLag\n    Essentials: All commands for Essentials\n    LuckPerms: All commands for LuckPerms\n    Minecraft: All commands for Minecraft\n    Vault: All commands for Vault\n    WorldEdit: All commands for WorldEdit\n\n Much easier to read and process. mctools handles this operation automatically, so you don't have to.\n mctools also handles situations where content is sent in ChatObject notation, and can extract messages from the \n player sample list.\n\n To learn more about formatters, and how to create your own, \n then please check out the [formatting documentation](https://mctools.readthedocs.io/en/latest/format.html).\n\n # MCLI - mctools Command Line Interface\n\n mctools is shipped with a CLI front end called mcli, which you can use to start rcon sessions, get stats\n via query/ping, check if a Minecraft server is up, ect. \n\n After installing mctools(through pip or setuptools), you can invoke mcli like so:\n\n    $ mcli --help\n\n You can also run mcli.py(which is located in the parent directory) if you downloaded the source code and did not\n install via pip/setuptools.\n\n The above command will generate the help menu for mcli. To learn more about mcli, please check out the \n [mcli documentation](https://mctools.readthedocs.io/en/latest/mcli.html).\n\n # Documentation\n\n mctools has an extensive documentation. It contains tutorials, the API reference, and best practice recommendations.\n You can find the [documentation here](https://mctools.readthedocs.io/).\n\n Be sure to also check out the [mctools PyPi page](https://pypi.org/project/mctools/) for more information.\n\n # Contributing\n\n Pull requests are welcome and encouraged :) ! If you want to see a feature in mctools, a PR will be the quickest \n way to get it included. Feel free to email me or open an issue if you have any problems.\n\n If you are interested in helping in the development of mctools, then send me an email, and we can get talking!\n Believe me, there is plenty of work that needs to be done. More help would be greatly appreciated!\n\n # Changelog\n\n ## 1.1.0\n\n This update adds some minor features and fixes some major bugs:\n\n  ### Bug Fixes:\n\n - Fixed RCON packet fragmentation issue, mctools should now properly detect and handle RCON packet fragmentation\n - Fixed bug where PINGFormatter was looking for 'dark_grey' instead of 'dark_gray'\n - Fixed bug where ChatObjectFormatter did not properly parse ChatObjects\n - We now raise an exception if the RCON write data is too big, instead of leaving the connection in a unstable state\n\n  ### Features Added:\n\n - Users can now specify the format method on a per-call basis\n - Users can change the timeout value after the object is instantiated\n - The RCON login check feature can be disabled, meaning that you can attempt to send packets\n even if you are not authenticated\n - Clients can now return raw packets\n - RCON now has custom exceptions\n\n This update is a prelude to another update I have working on.\n The next update will add numerous features, such as:\n\n - RCON Mixins for easing the process of getting/editing the following info:\n   - Players connected\n   - World Seed\n   - Game Rules\n   - Target Selectors\n   - Many more...\n - Custom exceptions for Ping and Query\n - Even Better error handling\n - mcli RCON command/argument autocompletion\n - Custom datatypes for all operations\n - RCON SSH Forwarding support\n (You can technically do this as of now, but I want the library to invoke and handle this process) for a more\n secure RCON experience\n - Unit tests for mctools\n\n I have some of these complete as of now, but I wanted to push out the big bug fixes and minor stuff before \n I finish creating and refining the features, as they may take me some time to implement.\n\n All of these features will be completely optional, and they will all be backwards compatible.\n So if you like the library as it is now, then you can completely ignore these new features.\n\n The documentation has been updated to reflect these changes.\n\n # Conclusion\n\n mctools offers a pythonic, reliable way to interact with Minecraft servers, without being too complicated.\n Please check the documentation for more information. More features (hopefully) coming soon!\n\n Thank you for reading!\n\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "Python implementations of common Minecraft protocols.",
    "version": "1.1.0",
    "split_keywords": [
        "minecraft",
        "rcon",
        "query",
        "ping",
        "server list ping"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "c828e1963e9dc9e15db03ced8e7b7fad",
                "sha256": "5962092c17190589459d5be3bf1ec506bdb6261d2da1bd9795d3b592938c8612"
            },
            "downloads": -1,
            "filename": "mctools-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c828e1963e9dc9e15db03ced8e7b7fad",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.6, <4",
            "size": 30153,
            "upload_time": "2020-09-09T15:29:46",
            "upload_time_iso_8601": "2020-09-09T15:29:46.697287Z",
            "url": "https://files.pythonhosted.org/packages/31/d1/4bf6143ecc8025c8405c40f04e9e7d5e03d43972be28d902e35d25b56d59/mctools-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "d720d505f6ce123e1a2d5ba3f7f127d6",
                "sha256": "a929e30fd08f2a79a9abda6abc25ca6fbf7ca4e6789bf52fcd55c6c0a430f401"
            },
            "downloads": -1,
            "filename": "mctools-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "d720d505f6ce123e1a2d5ba3f7f127d6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.6, <4",
            "size": 32936,
            "upload_time": "2020-09-09T15:29:47",
            "upload_time_iso_8601": "2020-09-09T15:29:47.949817Z",
            "url": "https://files.pythonhosted.org/packages/06/36/6a39472d15f8f37ae7d0522c6f7c8b2d17e24fce854fc8cb375a773e53a5/mctools-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2020-09-09 15:29:47",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": null,
    "github_project": "Owen-Cochell",
    "error": "Could not fetch GitHub repository",
    "lcname": "mctools"
}
        
Elapsed time: 0.12743s