%define scl rh-python36 %{?scl:%scl_package %{name}} %{!?scl:%global pkg_name %{name}} %define name irc %define version 18.0.0 %define unmangled_version 18.0.0 %define unmangled_version 18.0.0 %define release 1 Summary: IRC (Internet Relay Chat) protocol library for Python %{?scl:Requires: %{scl}-runtime} %{?scl:BuildRequires: %{scl}-runtime} Name: %{?scl_prefix}%{pkg_name} Version: %{version} Release: %{release} Source0: irc-%{unmangled_version}.tar.gz License: UNKNOWN Group: Development/Libraries BuildRoot: %{_tmppath}/%{pkg_name}-%{version}-%{release}-buildroot Prefix: %{_prefix} BuildArch: noarch Vendor: Jason R. Coombs Packager: Martin Juhl Url: https://github.com/jaraco/irc %description .. image:: https://img.shields.io/pypi/v/irc.svg :target: https://pypi.org/project/irc .. image:: https://img.shields.io/pypi/pyversions/irc.svg .. image:: https://img.shields.io/travis/jaraco/irc/master.svg :target: http://travis-ci.org/jaraco/irc .. image:: https://readthedocs.org/projects/python-irc/badge/?version=latest :target: http://python-irc.readthedocs.io/en/latest/?badge=latest .. image:: https://badges.gitter.im/jaraco/irc.svg :alt: Join the chat at https://gitter.im/jaraco/irc :target: https://gitter.im/jaraco/irc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge Full-featured Python IRC library for Python. - `Project home `_ - `Docs `_ - `History `_ Overview ======== This library provides a low-level implementation of the IRC protocol for Python. It provides an event-driven IRC client framework. It has a fairly thorough support for the basic IRC protocol, CTCP, and DCC connections. In order to understand how to make an IRC client, it's best to read up first on the `IRC specifications `_. Installation ============ IRC requires Python versions specified in the `download pages `_ and definitely supports Python 3. You have several options to install the IRC project. * Use ``easy_install irc`` or ``pip install irc`` to grab the latest version from the cheeseshop (recommended). * Run ``python setup.py install`` (from the source distribution). Client Features =============== The main features of the IRC client framework are: * Abstraction of the IRC protocol. * Handles multiple simultaneous IRC server connections. * Handles server PONGing transparently. * Messages to the IRC server are done by calling methods on an IRC connection object. * Messages from an IRC server triggers events, which can be caught by event handlers. * Reading from and writing to IRC server sockets is normally done by an internal ``select()`` loop, but the ``select()`` may be done by an external main loop. * Functions can be registered to execute at specified times by the event-loop. * Decodes CTCP tagging correctly (hopefully); I haven't seen any other IRC client implementation that handles the CTCP specification subtilties. * A kind of simple, single-server, object-oriented IRC client class that dispatches events to instance methods is included. * DCC connection support. Current limitations: * The IRC protocol shines through the abstraction a bit too much. * Data is not written asynchronously to the server (and DCC peers), i.e. the ``write()`` may block if the TCP buffers are stuffed. * Like most projects, documentation is lacking ... Unfortunately, this library isn't as well-documented as I would like it to be. I think the best way to get started is to read and understand the example program ``irccat``, which is included in the distribution. The following modules might be of interest: * ``irc.client`` The library itself. Read the code along with comments and docstrings to get a grip of what it does. Use it at your own risk and read the source, Luke! * ``irc.bot`` An IRC bot implementation. * ``irc.server`` A basic IRC server implementation. Suitable for testing, but not intended as a production service. Invoke the server with ``python -m irc.server``. Examples ======== Example scripts in the scripts directory: * ``irccat`` A simple example of how to use the IRC client. ``irccat`` reads text from stdin and writes it to a specified user or channel on an IRC server. * ``irccat2`` The same as above, but using the ``SimpleIRCClient`` class. * ``servermap`` Another simple example. ``servermap`` connects to an IRC server, finds out what other IRC servers there are in the net and prints a tree-like map of their interconnections. * ``testbot`` An example bot that uses the ``SingleServerIRCBot`` class from ``irc.bot``. The bot enters a channel and listens for commands in private messages or channel traffic. It also accepts DCC invitations and echos back sent DCC chat messages. * ``dccreceive`` Receives a file over DCC. * ``dccsend`` Sends a file over DCC. NOTE: If you're running one of the examples on a unix command line, you need to escape the ``#`` symbol in the channel. For example, use ``\\#test`` or ``"#test"`` instead of ``#test``. Scheduling Events ================= The library includes a default event Scheduler as ``irc.schedule.DefaultScheduler``, but this scheduler can be replaced with any other scheduler. For example, to use the `schedule `_ package, include it in your dependencies and install it into the IRC library as so: class ScheduleScheduler(irc.schedule.IScheduler): def execute_every(self, period, func): schedule.every(period).do(func) def execute_at(self, when, func): schedule.at(when).do(func) def execute_after(self, delay, func): raise NotImplementedError("Not supported") def run_pending(self): schedule.run_pending() irc.client.Reactor.scheduler_class = ScheduleScheduler Decoding Input ============== By default, the IRC library attempts to decode all incoming streams as UTF-8, even though the IRC spec stipulates that no specific encoding can be expected. Since assuming UTF-8 is not reasonable in the general case, the IRC library provides options to customize decoding of input by customizing the ``ServerConnection`` class. The ``buffer_class`` attribute on the ``ServerConnection`` determines which class is used for buffering lines from the input stream, using the ``buffer`` module in `jaraco.stream `_. By default it is ``buffer.DecodingLineBuffer``, but may be re-assigned with another class, following the interface of ``buffer.LineBuffer``. The ``buffer_class`` attribute may be assigned for all instances of ``ServerConnection`` by overriding the class attribute. For example: .. code:: python from jaraco.stream import buffer irc.client.ServerConnection.buffer_class = buffer.LenientDecodingLineBuffer The ``LenientDecodingLineBuffer`` attempts UTF-8 but falls back to latin-1, which will avoid ``UnicodeDecodeError`` in all cases (but may produce unexpected behavior if an IRC user is using another encoding). The buffer may be overridden on a per-instance basis (as long as it's overridden before the connection is established): .. code:: python server = irc.client.IRC().server() server.buffer_class = buffer.LenientDecodingLineBuffer server.connect() Alternatively, some clients may still want to decode the input using a different encoding. To decode all input as latin-1 (which decodes any input), use the following: .. code:: python irc.client.ServerConnection.buffer_class.encoding = 'latin-1' Or decode to UTF-8, but use a replacement character for unrecognized byte sequences: .. code:: python irc.client.ServerConnection.buffer_class.errors = 'replace' Or, to simply ignore all input that cannot be decoded: .. code:: python class IgnoreErrorsBuffer(buffer.DecodingLineBuffer): def handle_exception(self): pass irc.client.ServerConnection.buffer_class = IgnoreErrorsBuffer On Python 2, it was possible to use the ``buffer.LineBuffer`` itself, which will pass the raw bytes. On Python 3, the library requires text for message processing, so a decoding buffer must be used. Therefore, use of the ``LineBuffer`` is considered deprecated and not supported on Python 3. Clients should use one of the above techniques for decoding input to text. Notes and Contact Info ====================== Enjoy. Maintainer: Jason R. Coombs Original Author: Joel Rosdahl Copyright © 1999-2002 Joel Rosdahl Copyright © 2011-2016 Jason R. Coombs Copyright © 2009 Ferry Boender %prep %{?scl:scl enable %{scl} - << \EOF} set -ex %setup -n irc-%{unmangled_version} -n irc-%{unmangled_version} %{?scl:EOF} %build %{?scl:scl enable %{scl} - << \EOF} set -ex python3 setup.py build %{?scl:EOF} %install %{?scl:scl enable %{scl} - << \EOF} set -ex python3 setup.py install --single-version-externally-managed -O1 --root=$RPM_BUILD_ROOT --record=INSTALLED_FILES %{?scl:EOF} %clean %{?scl:scl enable %{scl} - << \EOF} set -ex rm -rf $RPM_BUILD_ROOT %{?scl:EOF} %files -f INSTALLED_FILES %defattr(-,root,root)