| Name | irc JSON |
| Version |
20.4.0
JSON |
| download |
| home_page | https://github.com/jaraco/irc |
| Summary | IRC (Internet Relay Chat) protocol library for Python |
| upload_time | 2024-03-28 13:44:23 |
| maintainer | None |
| docs_url | None |
| author | Jason R. Coombs |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
.. 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://github.com/jaraco/irc/actions/workflows/main.yml/badge.svg
:target: https://github.com/jaraco/irc/actions?query=workflow%3A%22tests%22
:alt: tests
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json
:target: https://github.com/astral-sh/ruff
:alt: Ruff
.. image:: https://readthedocs.org/projects/irc/badge/?version=latest
:target: https://irc.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/badge/skeleton-2024-informational
:target: https://blog.jaraco.com/skeleton
.. 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
.. image:: https://tidelift.com/badges/github/jaraco/irc
:target: https://tidelift.com/subscription/pkg/pypi-irc?utm_source=pypi-irc&utm_medium=referral&utm_campaign=readme
Full-featured Python IRC library for Python.
- `Project home <https://github.com/jaraco/irc>`_
- `Docs <https://python-irc.readthedocs.io/>`_
- `History <https://python-irc.readthedocs.io/en/latest/history.html>`_
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
<http://web.archive.org/web/20160628193730/http://www.irchelp.org/irchelp/rfc/>`_.
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.
* Multiple options for reading from and writing to an IRC server:
you can use sockets in an internal ``select()`` loop OR use
Python3's asyncio event 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 subtleties.
* 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 ...
* DCC is not currently implemented in the asyncio-based version
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.client_aio``
All the functionality of the above library, but utilizing
Python 3's native asyncio library for the core event loop.
Interface/API is otherwise functionally identical to the classes
in ``irc.client``
* ``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.
* ``aio_irccat``
Same as above, but uses the asyncio-based event loop in
``AioReactor`` instead of the ``select()`` based ``Reactor``.
* ``aio_irccat2``
Same as above, but using the ``AioSimpleIRCClient`` 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 <https://pypi.org/project/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
<https://pypi.python.org/pypi/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.Reactor().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
The library requires text for message
processing, so a decoding buffer must be used. Clients
must use one of the above techniques for decoding input to text.
Notes and Contact Info
======================
Enjoy.
Maintainer:
Jason R. Coombs <jaraco@jaraco.com>
Original Author:
Joel Rosdahl <joel@rosdahl.net>
Copyright © 1999-2002 Joel Rosdahl
Copyright © 2011-2016 Jason R. Coombs
Copyright © 2009 Ferry Boender
For Enterprise
==============
Available as part of the Tidelift Subscription.
This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.
`Learn more <https://tidelift.com/subscription/pkg/pypi-irc?utm_source=pypi-irc&utm_medium=referral&utm_campaign=github>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/jaraco/irc",
"name": "irc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Jason R. Coombs",
"author_email": "jaraco@jaraco.com",
"download_url": "https://files.pythonhosted.org/packages/b7/a7/ff31e45b46e5b98afe170de99cc3420ee706ed1fc1add15d647beff5e80a/irc-20.4.0.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/irc.svg\n :target: https://pypi.org/project/irc\n\n.. image:: https://img.shields.io/pypi/pyversions/irc.svg\n\n.. image:: https://github.com/jaraco/irc/actions/workflows/main.yml/badge.svg\n :target: https://github.com/jaraco/irc/actions?query=workflow%3A%22tests%22\n :alt: tests\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json\n :target: https://github.com/astral-sh/ruff\n :alt: Ruff\n\n.. image:: https://readthedocs.org/projects/irc/badge/?version=latest\n :target: https://irc.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/badge/skeleton-2024-informational\n :target: https://blog.jaraco.com/skeleton\n\n.. image:: https://badges.gitter.im/jaraco/irc.svg\n :alt: Join the chat at https://gitter.im/jaraco/irc\n :target: https://gitter.im/jaraco/irc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n\n.. image:: https://tidelift.com/badges/github/jaraco/irc\n :target: https://tidelift.com/subscription/pkg/pypi-irc?utm_source=pypi-irc&utm_medium=referral&utm_campaign=readme\n\nFull-featured Python IRC library for Python.\n\n- `Project home <https://github.com/jaraco/irc>`_\n- `Docs <https://python-irc.readthedocs.io/>`_\n- `History <https://python-irc.readthedocs.io/en/latest/history.html>`_\n\nOverview\n========\n\nThis library provides a low-level implementation of the IRC protocol for\nPython. It provides an event-driven IRC client framework. It has\na fairly thorough support for the basic IRC protocol, CTCP, and DCC\nconnections.\n\nIn order to understand how to make an IRC client, it's best to read up first\non the `IRC specifications\n<http://web.archive.org/web/20160628193730/http://www.irchelp.org/irchelp/rfc/>`_.\n\nClient Features\n===============\n\nThe main features of the IRC client framework are:\n\n* Abstraction of the IRC protocol.\n* Handles multiple simultaneous IRC server connections.\n* Handles server PONGing transparently.\n* Messages to the IRC server are done by calling methods on an IRC\n connection object.\n* Messages from an IRC server triggers events, which can be caught\n by event handlers.\n* Multiple options for reading from and writing to an IRC server:\n you can use sockets in an internal ``select()`` loop OR use\n Python3's asyncio event loop\n* Functions can be registered to execute at specified times by the\n event-loop.\n* Decodes CTCP tagging correctly (hopefully); I haven't seen any\n other IRC client implementation that handles the CTCP\n specification subtleties.\n* A kind of simple, single-server, object-oriented IRC client class\n that dispatches events to instance methods is included.\n* DCC connection support.\n\nCurrent limitations:\n\n* The IRC protocol shines through the abstraction a bit too much.\n* Data is not written asynchronously to the server (and DCC peers),\n i.e. the ``write()`` may block if the TCP buffers are stuffed.\n* Like most projects, documentation is lacking ...\n* DCC is not currently implemented in the asyncio-based version\n\nUnfortunately, this library isn't as well-documented as I would like\nit to be. I think the best way to get started is to read and\nunderstand the example program ``irccat``, which is included in the\ndistribution.\n\nThe following modules might be of interest:\n\n* ``irc.client``\n\n The library itself. Read the code along with comments and\n docstrings to get a grip of what it does. Use it at your own risk\n and read the source, Luke!\n\n* ``irc.client_aio``\n\n All the functionality of the above library, but utilizing\n Python 3's native asyncio library for the core event loop.\n Interface/API is otherwise functionally identical to the classes\n in ``irc.client``\n\n* ``irc.bot``\n\n An IRC bot implementation.\n\n* ``irc.server``\n\n A basic IRC server implementation. Suitable for testing, but not\n intended as a production service.\n\n Invoke the server with ``python -m irc.server``.\n\nExamples\n========\n\nExample scripts in the scripts directory:\n\n* ``irccat``\n\n A simple example of how to use the IRC client. ``irccat`` reads\n text from stdin and writes it to a specified user or channel on\n an IRC server.\n\n* ``irccat2``\n\n The same as above, but using the ``SimpleIRCClient`` class.\n\n* ``aio_irccat``\n\n Same as above, but uses the asyncio-based event loop in\n ``AioReactor`` instead of the ``select()`` based ``Reactor``.\n\n\n* ``aio_irccat2``\n\n Same as above, but using the ``AioSimpleIRCClient`` class\n\n\n* ``servermap``\n\n Another simple example. ``servermap`` connects to an IRC server,\n finds out what other IRC servers there are in the net and prints\n a tree-like map of their interconnections.\n\n* ``testbot``\n\n An example bot that uses the ``SingleServerIRCBot`` class from\n ``irc.bot``. The bot enters a channel and listens for commands in\n private messages or channel traffic. It also accepts DCC\n invitations and echos back sent DCC chat messages.\n\n* ``dccreceive``\n\n Receives a file over DCC.\n\n* ``dccsend``\n\n Sends a file over DCC.\n\n\nNOTE: If you're running one of the examples on a unix command line, you need\nto escape the ``#`` symbol in the channel. For example, use ``\\\\#test`` or\n``\"#test\"`` instead of ``#test``.\n\n\nScheduling Events\n=================\n\nThe library includes a default event Scheduler as\n``irc.schedule.DefaultScheduler``,\nbut this scheduler can be replaced with any other scheduler. For example,\nto use the `schedule <https://pypi.org/project/schedule>`_ package,\ninclude it\nin your dependencies and install it into the IRC library as so:\n\n class ScheduleScheduler(irc.schedule.IScheduler):\n def execute_every(self, period, func):\n schedule.every(period).do(func)\n\n def execute_at(self, when, func):\n schedule.at(when).do(func)\n\n def execute_after(self, delay, func):\n raise NotImplementedError(\"Not supported\")\n\n def run_pending(self):\n schedule.run_pending()\n\n irc.client.Reactor.scheduler_class = ScheduleScheduler\n\n\nDecoding Input\n==============\n\nBy default, the IRC library attempts to decode all incoming streams as\nUTF-8, even though the IRC spec stipulates that no specific encoding can be\nexpected. Since assuming UTF-8 is not reasonable in the general case, the IRC\nlibrary provides options to customize decoding of input by customizing the\n``ServerConnection`` class. The ``buffer_class`` attribute on the\n``ServerConnection`` determines which class is used for buffering lines from the\ninput stream, using the ``buffer`` module in `jaraco.stream\n<https://pypi.python.org/pypi/jaraco.stream>`_. By default it is\n``buffer.DecodingLineBuffer``, but may be\nre-assigned with another class, following the interface of ``buffer.LineBuffer``.\nThe ``buffer_class`` attribute may be assigned for all instances of\n``ServerConnection`` by overriding the class attribute.\n\nFor example:\n\n.. code:: python\n\n from jaraco.stream import buffer\n\n irc.client.ServerConnection.buffer_class = buffer.LenientDecodingLineBuffer\n\nThe ``LenientDecodingLineBuffer`` attempts UTF-8 but falls back to latin-1, which\nwill avoid ``UnicodeDecodeError`` in all cases (but may produce unexpected\nbehavior if an IRC user is using another encoding).\n\nThe buffer may be overridden on a per-instance basis (as long as it's\noverridden before the connection is established):\n\n.. code:: python\n\n server = irc.client.Reactor().server()\n server.buffer_class = buffer.LenientDecodingLineBuffer\n server.connect()\n\nAlternatively, some clients may still want to decode the input using a\ndifferent encoding. To decode all input as latin-1 (which decodes any input),\nuse the following:\n\n.. code:: python\n\n irc.client.ServerConnection.buffer_class.encoding = \"latin-1\"\n\nOr decode to UTF-8, but use a replacement character for unrecognized byte\nsequences:\n\n.. code:: python\n\n irc.client.ServerConnection.buffer_class.errors = \"replace\"\n\nOr, to simply ignore all input that cannot be decoded:\n\n.. code:: python\n\n class IgnoreErrorsBuffer(buffer.DecodingLineBuffer):\n def handle_exception(self):\n pass\n\n\n irc.client.ServerConnection.buffer_class = IgnoreErrorsBuffer\n\nThe library requires text for message\nprocessing, so a decoding buffer must be used. Clients\nmust use one of the above techniques for decoding input to text.\n\nNotes and Contact Info\n======================\n\nEnjoy.\n\nMaintainer:\nJason R. Coombs <jaraco@jaraco.com>\n\nOriginal Author:\nJoel Rosdahl <joel@rosdahl.net>\n\nCopyright \u00a9 1999-2002 Joel Rosdahl\nCopyright \u00a9 2011-2016 Jason R. Coombs\nCopyright \u00a9 2009 Ferry Boender\n\nFor Enterprise\n==============\n\nAvailable as part of the Tidelift Subscription.\n\nThis project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.\n\n`Learn more <https://tidelift.com/subscription/pkg/pypi-irc?utm_source=pypi-irc&utm_medium=referral&utm_campaign=github>`_.\n",
"bugtrack_url": null,
"license": null,
"summary": "IRC (Internet Relay Chat) protocol library for Python",
"version": "20.4.0",
"project_urls": {
"Homepage": "https://github.com/jaraco/irc"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d3e968e68fa9b006b33cca9d50991afc472feeb04a5dddfe91f0e7ea17cc35b7",
"md5": "2412699540a906433533428dc0b6d114",
"sha256": "7b70cd3913d9774255df8f4bd56ca07850d3120ec16f3824b152f32670359655"
},
"downloads": -1,
"filename": "irc-20.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2412699540a906433533428dc0b6d114",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 74824,
"upload_time": "2024-03-28T13:44:19",
"upload_time_iso_8601": "2024-03-28T13:44:19.736881Z",
"url": "https://files.pythonhosted.org/packages/d3/e9/68e68fa9b006b33cca9d50991afc472feeb04a5dddfe91f0e7ea17cc35b7/irc-20.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b7a7ff31e45b46e5b98afe170de99cc3420ee706ed1fc1add15d647beff5e80a",
"md5": "b04b8eaac6cee916c51223d6d9299453",
"sha256": "7d2517f5566d6bf3aa85d7f98c7758b61f0d63ee915bfd9f6f567139736644f9"
},
"downloads": -1,
"filename": "irc-20.4.0.tar.gz",
"has_sig": false,
"md5_digest": "b04b8eaac6cee916c51223d6d9299453",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 91215,
"upload_time": "2024-03-28T13:44:23",
"upload_time_iso_8601": "2024-03-28T13:44:23.303593Z",
"url": "https://files.pythonhosted.org/packages/b7/a7/ff31e45b46e5b98afe170de99cc3420ee706ed1fc1add15d647beff5e80a/irc-20.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-28 13:44:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jaraco",
"github_project": "irc",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "irc"
}
