Kangaroo Sockets 🦘

Kangaroo is a user-friendly lib for sockets in Python. You can send and listen to TCP sockets with a few lines of code.

Contents

• Installation
• Quick start
• Documentation
• Examples
• Development
• Testing
• Contributing
• License

Installation

First you need Python installed (version 3.6+ is required), then you can install Kangaroo:

$ pip install kangaroo-sockets

Import it ib your code:

import Kangaroo

(Optional) install Jaguar for testing the sockets:

$ brew tap leozz37/jaguar

$ brew install jaguar

Quick start

Sample code for sending and listening to a port:

from src.kangaroo import Kangaroo
import threading
import time


def listen_port(port: int):
    r = Kangaroo().listen(port)

    while True:
        if r.has_new_message():
            print(r.get_message())


if __name__ == '__main__':
    x = threading.Thread(target=listen_port, args=(3000,))
    y = threading.Thread(target=listen_port, args=(3001,))

    x.start()
    y.start()

    while True:
        Kangaroo().send(3000, "Hello")
        Kangaroo().send(3001, "World")
        time.sleep(1)

Documentation

The library consists on two features: listen and send to a given port. You can check the full documentation on pypi.

---

Listen

Receives a port as int and returns a Kangaroo instance.

def listen(self, port: int):

Usage example:

kangaroo = Kangaroo()

r = kangaroo.listen(3000)
l = kangaroo.listen(3001)

---

Send

Receives a port and a message, both as string.

def send(self, port: int, message: str) -> None:

Usage example:

kangaroo = Kangaroo()

r = kangaroo.listen(3000)
kangaroo.send(3000, "Hello, World!")

Messages

has_new_messages() returns a bool if there's a new message:

def has_new_message(self) -> bool:

get_message() returns the last message as str:

def get_message(self) -> str:

Usage example:

import Kangaroo


if __name__ == '__main__':
    kangaroo = Kangaroo()

    r = kangaroo.listen(3000)
    kangaroo.send(3000, "Hello world")

    if r.has_new_message():
        print(r.get_message())

Development

This project uses pipenv and pre-commit in order to run some static checks and formatting on the code. After clone the repository you need to create a new virtual environment and install the dependencies:

$ pipenv shell

$ pipenv install --dev --skip-lock

$ pre-commit install

Every time you run the git commit command the code will be checked. To run the checking manually, run:

$ pre-commit run --all-files

Testing

The tests uses the pytest framework. To run the test suit with coverage you can do the following:

$ pytest --cov=. -v

============================================================================================================================ test session starts ============================================================================================================================
platform darwin -- Python 3.8.2, pytest-6.1.2, py-1.9.0, pluggy-0.13.1 -- /Library/Developer/CommandLineTools/usr/bin/python3
cachedir: .pytest_cache
rootdir: /Users/leo/Documents/codes/kangaroo
plugins: cov-2.10.1
collected 4 items

tests/kangaroo_test.py::test_send_with_success PASSED                                                                                                                                                                                                                 [ 25%]
tests/kangaroo_test.py::test_listen_with_success PASSED                                                                                                                                                                                                               [ 50%]
tests/kangaroo_test.py::test_get_message_fails PASSED                                                                                                                                                                                                                 [ 75%]
tests/kangaroo_test.py::test_has_new_message_fails PASSED                                                                                                                                                                                                             [100%]

---------- coverage: platform darwin, python 3.8.2-final-0 -----------
Name                     Stmts   Miss  Cover
--------------------------------------------
__init__.py                  3      0   100%
setup.py                     4      4     0%
src/__init__.py              0      0   100%
src/kangaroo.py             31      0   100%
tests/__init__.py            0      0   100%
tests/kangaroo_test.py      23      0   100%
--------------------------------------------
TOTAL                       61      4    93%

Contributing

A full guideline about contributing to Kangaroo can be found in the CONTRIBUTING.md file.

License

Hare is released under the MIT License.