Introduction
============

This guide will go through installing **berconpy** and using it to connect
to a server, send commands, and receive messages.

Requirements
------------

The minimum Python version required is **3.10**.
No other external dependencies are required.

Installation
------------

This library can be installed from PyPI using one of the following commands:

.. code-block:: sh

    # Linux/macOS
    python3 -m pip install berconpy

    # Windows
    py -m pip install berconpy

To install the development version of the library, you can download
it from GitHub directly:

.. code-block:: sh

    # Windows
    py -m pip install git+https://github.com/thegamecracks/berconpy

.. note::

    The above command requires Git_ to be installed.

.. _Git: https://git-scm.com/

Basic Usage
-----------

The primary class berconpy offers is the :py:class:`~berconpy.AsyncRCONClient`,
which provides an interface over the underlying protocol and allows you to
register event listeners and send commands to the BattlEye RCON server.

Sending commands
^^^^^^^^^^^^^^^^

Let's start with an example of how to send a command:

.. code:: python

    import asyncio
    import berconpy as rcon

    IP_ADDR = "XXX.XXX.XXX.XXX"
    PORT = 9999
    PASSWORD = "ASCII_PASSWORD"

    client = rcon.AsyncRCONClient()

    async def main():
        async with client.connect(IP_ADDR, PORT, PASSWORD):
            response = await client.send_command("players")
            print(response)

    asyncio.run(main())

.. note::

    The RCON IP address, port, and password can be found in your server's
    ``BEServer.cfg`` / ``BEServer_x64.cfg``.

1. ``client = rcon.AsyncRCONClient()`` creates the client instance.
   No arguments are necessary, but you can set up event listeners
   on the client before beginning any connection which will be
   demonstrated afterwards.

2. ``async with client.connect(IP_ADDR, PORT, PASSWORD)`` attempts to connect
   and log into the RCON server. The context manager also keeps the connection
   alive until you exit it, or an error occurs.

3. ``response = await client.send_command("players")`` requests the
   players currently connected to the server and returns a string.

:py:meth:`~berconpy.AsyncRCONClient.send_command()` provides a low-level
method for sending commands. Certain commands are already available as methods,
like :py:meth:`~berconpy.AsyncRCONClient.fetch_players()` and
:py:meth:`~berconpy.AsyncRCONClient.whisper()`.
The `BattlEye documentation`_ describes server-side commands that can
be sent with ``send_command()``.

Event listeners
^^^^^^^^^^^^^^^

There are several events you can listen to handle messages sent by the server
in real-time. Below is an example of displaying in-game messages from players:

.. code:: python

    import asyncio
    import math
    import berconpy as rcon

    IP_ADDR = "XXX.XXX.XXX.XXX"
    PORT = 9999
    PASSWORD = "ASCII_PASSWORD"

    client = rcon.AsyncRCONClient()

    @client.dispatch.on_player_message
    async def on_player_message(player: rcon.Player, channel: str, message: str):
        print(f"({channel}) {player.name}: {message}")

    async def main():
        async with client.connect(IP_ADDR, PORT, PASSWORD):
            await asyncio.sleep(math.inf)  # Keep client alive indefinitely

    asyncio.run(main())

The :py:meth:`@client.dispatch.on_player_message <berconpy.AsyncEventDispatcher.on_player_message>`
decorator adds a function as a listener for that specific event when it is
received from the server. All ``on_*`` methods provided by
:py:attr:`@client.dispatch <berconpy.AsyncRCONClient.dispatch>` have function signatures
that allow your type checker to ensure that your listener is correctly typed.
For a full list of events, see the :py:class:`~berconpy.dispatch.EventDispatcher`.

You might have also noticed in the listener that it receives a
:py:class:`~berconpy.Player` instance as its first argument.
The client instance manages a cache of players which makes it easier to
perform operations on different players like whispering and kicking.
A list of players can be retrieved through the
:py:attr:`~berconpy.AsyncRCONClient.players` property.

Configuring Logging
-------------------

**berconpy** allows logging information about the protocol and the client
during runtime with the built-in :py:mod:`logging` module. By default,
no logging configuration is used. You can set up logging either by calling
:py:func:`logging.basicConfig()` (which configures the root logger)
or by adding your own handlers to the ``berconpy`` logger.

The following table describes what messages are shown in each level of logging:

======== =============================================================
Level    Messages
======== =============================================================
CRITICAL *Unused*
   ERROR Potentially fatal connection errors (e.g. incorrect password)
 WARNING Failed commands and consecutive reconnects
    INFO Connection attempts and timeouts
   DEBUG Events and packets transmitted/received
======== =============================================================

Example configurations
^^^^^^^^^^^^^^^^^^^^^^

Log all messages to stderr:

.. code:: python

    import logging

    logging.basicConfig(level=logging.DEBUG)

Log berconpy warnings to ``berconpy.log``:

.. code:: python

    import logging

    log = logging.getLogger("berconpy")
    log.setLevel(logging.WARNING)
    handler = logging.FileHandler("berconpy.log", "w")
    handler.setFormatter(logging.Formatter("%(asctime)s:%(levelname)s:%(name)s: %(message)s"))
    log.addHandler(handler)

Next Steps
----------

This has covered the fundamentals of using berconpy. You can learn more about
the available methods by checking the :doc:`/asyncio`, or if you're interested
in the technical details you can `check the source code`_.

.. _BattlEye documentation: https://www.battleye.com/support/documentation/
.. _check the source code: https://github.com/thegamecracks/berconpy/tree/main/src/berconpy