From 705a84f5b8908b462a0c0c98b64d5d111ec20d17 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Wed, 15 Jul 2020 23:08:11 -0500 Subject: Change how address and socket are determined in Lirc This is to help with making this package cross-platform. --- docs/source/usage.rst | 57 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 9 deletions(-) (limited to 'docs/source/usage.rst') diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 588d2f7..ef9aa96 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -16,16 +16,16 @@ of things you can now import from it to get started. ) The most relevant of these is ``Lirc``, since this is the main class -you will be using. +you will be using. ``LircResponse`` is the response object that is returned +when you send a command. All the others are just errors. Initializing Lirc ----------------- -The ``Lirc`` class takes in three separate options, which all have default -values, that we may pass into it to construct it and override those default -values. - -The simplest way to construct ``Lirc`` is with no arguments at all. +The ``Lirc`` class takes in three separate options: ``address``, ``socket``, +and ``timeout``. These all have default values that depend on the operating +system you are on. So the simplest way to construct ``Lirc`` is with no +arguments at all. .. code-block:: python @@ -33,6 +33,45 @@ The simplest way to construct ``Lirc`` is with no arguments at all. lirc = Lirc() -This will attempt to connect to the lircd socket at "/var/run/lirc/lircd" on -your system, create a socket using ``AF_UNIX`` and ``SOCK_STREAM``, and sets -a socket timeout of 5 seconds. \ No newline at end of file +Overriding LIRC Defaults on Initialization +------------------------------------------ + +However, if we the defaults don't work for us? Let's say we're on Windows +and we want to connect over TCP to a remote LIRC server on another Windows +machine. So we've passed in an ``address`` to override the default so it doesn't +look for the daemon on the localhost. ``socket`` and ``timeout`` are passed in +just to show that we can, these are already the defaults on Windows. + +.. code-block:: python + + import socket + from lirc import Lirc + + lirc = Lirc( + address=("10.16.30.2", 8765), + socket=socket.socket(socket.AF_INET, socket.SOCK_STREAM), + timeout=5 + ) + +LIRC Initialization Defaults per Operating System +----------------------------------------------- + +From the options we may pass into ``Lirc``, ``address`` and ``socket`` will +change depending on the operating system you are using. The ``timeout`` always +defaults to 5 (seconds). + +On Linux, this will attempt to connect to the lircd socket at +``/var/run/lirc/lircd`` and create a socket using ``AF_UNIX`` and +``SOCK_STREAM``. + +On macOS, it will be almost identical to Linux except that all the paths +on macOS will be prefixed by ``/opt/local/`` so the connection to the lircd +socket will instead be at ``/opt/local/var/run/lirc/lircd``. The socket that +is created will be the same. + +However if we are on Windows, we can't use unix domain sockets. So instead, +WinLIRC uses TCP to communicate with the lirc daemon. So instead of a string +for the address, it defaults to a tuple of ("localhost", 8765), the default on +WinLIRC. The first part contains the address whereas the second is the port. +Furthermore, the socket that is created uses ``AF_INET`` and ``SOCK_STREAM`` +instead now. -- cgit v1.2.3 From f9c60014ede3edda8569745b725f1b458bb400ff Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 3 Oct 2020 22:48:04 -0500 Subject: Update usage for Client --- docs/source/usage.rst | 48 ++++++++++++++++++++++-------------------------- 1 file changed, 22 insertions(+), 26 deletions(-) (limited to 'docs/source/usage.rst') diff --git a/docs/source/usage.rst b/docs/source/usage.rst index ef9aa96..9898459 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -6,32 +6,26 @@ of things you can now import from it to get started. .. code-block:: python - from lirc import ( - Lirc, - LircResponse, - LircError, - LircSocketError, - LircSocketTimeoutError, - InvalidReplyPacketFormatError - ) + from lirc import Client, LircdConnection -The most relevant of these is ``Lirc``, since this is the main class -you will be using. ``LircResponse`` is the response object that is returned -when you send a command. All the others are just errors. +The most relevant of these is ``Client``, since this is the main class +you will be using. ``LircdConnection`` is the object that is used to configure +the connection to LIRC when you initialize the ``Client``. Initializing Lirc ----------------- -The ``Lirc`` class takes in three separate options: ``address``, ``socket``, -and ``timeout``. These all have default values that depend on the operating -system you are on. So the simplest way to construct ``Lirc`` is with no +The ``Client`` class takes in one optional keyword argument: connection. +This connection must be a ``LircdConnection``. This connection, if not +specified manuall, will have default values that depend on the operating +system you are on. So the simplest way to construct ``Client`` is with no arguments at all. .. code-block:: python - from lirc import Lirc + from lirc import Client - lirc = Lirc() + lirc_client = Client() Overriding LIRC Defaults on Initialization ------------------------------------------ @@ -45,20 +39,22 @@ just to show that we can, these are already the defaults on Windows. .. code-block:: python import socket - from lirc import Lirc - - lirc = Lirc( - address=("10.16.30.2", 8765), - socket=socket.socket(socket.AF_INET, socket.SOCK_STREAM), - timeout=5 + from lirc import Client, LircdConnection + + client = Client( + connection=LircdConnection( + address=("10.16.30.2", 8765), + socket=socket.socket(socket.AF_INET, socket.SOCK_STREAM), + timeout=5.0 + ) ) LIRC Initialization Defaults per Operating System ----------------------------------------------- -From the options we may pass into ``Lirc``, ``address`` and ``socket`` will -change depending on the operating system you are using. The ``timeout`` always -defaults to 5 (seconds). +From the options we may pass into the ``LircdConnection``, ``address`` +and ``socket`` will change depending on the operating system you are using. +The ``timeout`` always defaults to 5.0 (seconds). On Linux, this will attempt to connect to the lircd socket at ``/var/run/lirc/lircd`` and create a socket using ``AF_UNIX`` and @@ -74,4 +70,4 @@ WinLIRC uses TCP to communicate with the lirc daemon. So instead of a string for the address, it defaults to a tuple of ("localhost", 8765), the default on WinLIRC. The first part contains the address whereas the second is the port. Furthermore, the socket that is created uses ``AF_INET`` and ``SOCK_STREAM`` -instead now. +instead so we can connect over TCP. -- cgit v1.2.3 From 9ec726bf42d84e086df525072f2faa40cc37d287 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 3 Oct 2020 22:56:16 -0500 Subject: Add windows configuration instructions --- docs/source/usage.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/source/usage.rst') diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 9898459..b007fd0 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -17,7 +17,7 @@ Initializing Lirc The ``Client`` class takes in one optional keyword argument: connection. This connection must be a ``LircdConnection``. This connection, if not -specified manuall, will have default values that depend on the operating +specified manually, will have default values that depend on the operating system you are on. So the simplest way to construct ``Client`` is with no arguments at all. @@ -65,9 +65,9 @@ on macOS will be prefixed by ``/opt/local/`` so the connection to the lircd socket will instead be at ``/opt/local/var/run/lirc/lircd``. The socket that is created will be the same. -However if we are on Windows, we can't use unix domain sockets. So instead, +However if we are on Windows, we can't use unix domain sockets. Instead, WinLIRC uses TCP to communicate with the lirc daemon. So instead of a string -for the address, it defaults to a tuple of ("localhost", 8765), the default on -WinLIRC. The first part contains the address whereas the second is the port. -Furthermore, the socket that is created uses ``AF_INET`` and ``SOCK_STREAM`` -instead so we can connect over TCP. +for the address, it defaults to a tuple of ("localhost", 8765), which is the +default on WinLIRC. The first part contains the address whereas the second is +the port. Furthermore, the socket that is created uses ``AF_INET`` and +``SOCK_STREAM`` instead so we can connect over TCP. -- cgit v1.2.3