summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-07-12 19:44:52 -0500
committerEugene Triguba <eugenetriguba@gmail.com>2020-07-12 19:44:52 -0500
commit32991facadab05d58bfef52ea871b22ef46f54f0 (patch)
treee656b388658f4cd3c9bed0ac533beb6977edee65
parentRemove readthedocs config (diff)
downloadlirc-32991facadab05d58bfef52ea871b22ef46f54f0.zip
Update docstrings in `Lirc` and add to readme
-rw-r--r--README.md61
-rw-r--r--lirc/lirc.py74
2 files changed, 98 insertions, 37 deletions
diff --git a/README.md b/README.md
index ec0556a..444ef4e 100644
--- a/README.md
+++ b/README.md
@@ -7,4 +7,63 @@
[![Black](https://img.shields.io/badge/style-black-black)](https://pypi.org/project/black/)
[![Documentation Status](https://readthedocs.org/projects/lirc/badge/?version=latest)](https://lirc.readthedocs.io/en/latest/?badge=latest)
[![Build Status](https://github.com/eugenetriguba/lirc/workflows/python%20package%20ci/badge.svg?branch=master)](https://github.com/eugenetriguba/lirc/actions/)
-[![Codecov](https://codecov.io/gh/eugenetriguba/lirc/graph/badge.svg)](https://codecov.io/gh/eugenetriguba/lirc) \ No newline at end of file
+[![Codecov](https://codecov.io/gh/eugenetriguba/lirc/graph/badge.svg)](https://codecov.io/gh/eugenetriguba/lirc)
+
+LIRC is a python package that allows you to interact with
+the daemon in the Linux Infrared Remote Control package.
+
+More information on the lircd daemon, socket interface,
+reply packet format, etc. can be found at https://www.lirc.org/html/lircd.html
+
+## Installation
+
+The package is hosted on PyPI and can be installed
+through pip.
+
+```
+$ pip install lirc
+```
+
+However since this is a wrapper around the LIRC daemon, it
+is expected that LIRC is installed and setup on the given
+system.
+
+## Usage
+
+```python
+from lirc import Lirc
+
+lirc = Lirc()
+response = lirc.version()
+
+print(response.command)
+>>> 'VERSION'
+print(response.success)
+>>> True
+print(response.data)
+>>> ['0.10.1']
+```
+
+To get started with the package, we import `Lirc` and can
+initialize it with the defaults by passing it no arguments.
+
+This will assume a socket path of `/var/run/lirc/lircd`.
+Furthermore, this will also then assume a socket connection
+using AF_UNIX and SOCK_STREAM. These are both the defaults
+that should work on a Linux system. There are ports of LIRC
+to Windows and macOS but using the package there is far less
+common. However, both of these are configurable through options
+passed to `Lirc` to allow it to be used on those operating systems
+as well.
+
+After sending any command to the LIRC daemon, this package will create
+a `LircResponse` for us that it returns. That response contains the
+command we sent to LIRC, whether it was successful, and any data that
+was returned back to us.
+
+Further documentation and a full API specification is available at
+https://lirc.readthedocs.org
+
+## License
+
+The [MIT](./LICENSE) License \ No newline at end of file
diff --git a/lirc/lirc.py b/lirc/lirc.py
index d0b0617..21a3d42 100644
--- a/lirc/lirc.py
+++ b/lirc/lirc.py
@@ -1,6 +1,7 @@
import socket
import threading
from itertools import islice
+from typing import List, Union
from lirc.exceptions import (
InvalidReplyPacketFormatError,
@@ -11,28 +12,7 @@ from lirc.response import LircResponse
class Lirc:
- """
- Communicate with the lircd daemon.
-
- More information on the lircd daemon, socket interface,
- reply packet format, etc. can be found at https://www.lirc.org/html/lircd.html
- That information is not all documented here because it would introduce
- a lot of repetitiveness in the docstrings.
-
- Example Usage:
-
- from lirc import Lirc
-
- lirc = Lirc()
- response = lirc.version()
-
- print(response.command)
- >>> 'VERSION'
- print(response.success)
- >>> True
- print(response.data)
- >>> ['0.10.1']
- """
+ """Communicate with the lircd daemon."""
DEFAULT_SOCKET_PATH = "/var/run/lirc/lircd"
ENCODING = "utf-8"
@@ -48,6 +28,8 @@ class Lirc:
:param socket_path: The path to the lircd socket.
:param socket: The socket.socket used to connect to the lircd socket.
+ :param socket_timeout: The amount of time to wait before timing out when
+ receiving data.
"""
self.__lock = threading.Lock()
self.__socket = socket
@@ -92,7 +74,8 @@ class Lirc:
n lines of data]
END
- :return: The contents of the reply packet from BEGIN to END as a str.
+ :return: The contents of the reply packet from BEGIN to END.
+
:raises LircSocketTimeoutError: If recv does not find any data after
self.socket_timeout amount of seconds.
:raises LircSocketError: If something else went wrong with the socket.
@@ -163,23 +146,25 @@ class Lirc:
return response
- def send_once(self, key: str, remote: str, repeat_count: int = 1) -> LircResponse:
+ def send_once(
+ self, key: str, remote: str, repeat_count: int = 1
+ ) -> Union[LircResponse, List[LircResponse]]:
"""
Send an LIRC SEND_ONCE command.
Structure of the command:
* SEND_ONCE <remote-name> <key-name-from-remote-file> [repeat-count]
- The reason the optional repeat-count parameter isn't used in this implementaiton
- is because we want to be able to store all the responses from each command.
-
:param key: The name of the key to send.
:param remote: The remote to use keys from.
:param repeat_count: The number of times to press this key.
- :return: a LircResponse or a list of LircResponses if repeat_count > 1.
- :rtype: LircResponse or list
+ :return: a response from the command or a list of those responses
+ if repeat_count > 1.
"""
+ # The reason the optional repeat-count parameter isn't used in this
+ # implementaiton is because we want to be able to store all the
+ # responses from each command.
if repeat_count > 1:
responses = []
@@ -200,6 +185,8 @@ class Lirc:
:param key: The name of the key to start sending.
:param remote: The remote to use keys from.
+
+ :return: The response of the command.
"""
return self.__send_command(f"SEND_START {remote} {key}")
@@ -212,11 +199,17 @@ class Lirc:
:param key: The name of the key to start sending.
:param remote: The remote to use keys from.
+
+ :return: The response of the command.
"""
return self.__send_command(f"SEND_STOP")
def list_remotes(self) -> LircResponse:
- """List all the remotes in LIRC"""
+ """
+ List all the remotes in LIRC
+
+ :return: The response of the command.
+ """
return self.__send_command("LIST")
def list_remote_keys(self, remote: str) -> LircResponse:
@@ -225,24 +218,33 @@ class Lirc:
:param remote: The remote to list the keys of.
- :return: An LircResponse containing the keys in the
- data section.
+ :return: The response of the command.
"""
return self.__send_command(f"LIST {remote}")
def set_inputlog(self, path: str) -> LircResponse:
- """Set the path to log all lircd received data to"""
+ """
+ Set the path to log all lircd received data to.
+
+ :return: The response of the command.
+ """
return self.__send_command(f"SET_INPUTLOG {path}")
def stop_inputlog(self) -> LircResponse:
"""
Stop logging to the inputlog path from set_inputlog.
- When calling SET_INPUTLOG without the path argument,
- it will stop logging and close the logfile.
+ :return: The response of the command.
"""
+ # When calling SET_INPUTLOG without the path argument,
+ # it will stop logging and close the logfile.
return self.__send_command("SET_INPUTLOG")
def version(self) -> LircResponse:
- """Retrieve the version of LIRC"""
+ """
+ Retrieve the version of LIRC
+
+ :return: The response of the command with
+ the version in the data field.
+ """
return self.__send_command("VERSION")