THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
dgw a5a6e2dcf3
Merge pull request #1901 from sopel-irc/document-env-vars
3 days ago
.github Add Python version to bug report issue template 4 months ago
contrib contrib: remove unused import in makerpm.py 7 months ago
docs doc: a bit more info about plugin names (conventions & how to specify) 4 days ago
sopel Merge pull request #1901 from sopel-irc/document-env-vars 3 days ago
test test: add coverage for `SOPEL_CONFIG_DIR` environment variable 1 week ago
.codeclimate.yml Tweak some thresholds in codeclimate config 1 year ago
.coveragerc test: update web -> tools.web; ignore deprecated package 11 months ago
.gitignore test: py.test Sopel plugin with test factories 7 months ago
.travis.yml travis: modernize base build images when possible 2 months ago
CONTRIBUTING.md CONTRIBUTING: Additional tweaks 1 month ago
COPYING Added EFL license file, to actually comply with it 7 years ago
CREDITS CREDITS: RustyBower name update, per IRC request [Skip CI] 6 months ago
MANIFEST.in install: use setup.cfg instead of setup.py 1 year ago
Makefile module, tests: set up `VCR.py` for plugin example tests 1 month ago
NEWS Release 7.0.4 1 month ago
NEWS.spec.md NEWS, NEWS.spec: 7.0+ will use a "Plugin changes" heading 5 months ago
README.rst README: Clean up some stuff for PyPI 5 months ago
checkstyle.sh checkstyle: Fix py3-unsafe unicode() detection 1 year ago
ci_build.sh Update ci_build.sh to be useful again 2 years ago
conftest.py test: provide "path" instead of "dir" fixture for old pytest-vcr 1 month ago
dev-requirements.txt module, tests: set up `VCR.py` for plugin example tests 1 month ago
pytest.ini Update to testing process 2 years ago
pytest_run.py Cleaning for flake8-import-order 1 month ago
requirements.txt requirements: cap urllib3 version on old Python releases 2 months ago
setup.cfg Cleaning for flake8-import-order 1 month ago
setup.py Cleaning for flake8-import-order 1 month ago
sopel.py Cleaning for flake8-import-order 1 month ago

README.rst

=======
Sopel
=======

|version| |build| |issues| |alerts| |coverage-status| |license|

Introduction
------------

Sopel is a simple, lightweight, open source, easy-to-use IRC Utility bot,
written in Python. It's designed to be easy to use, run and extend.

Installation
------------

Latest stable release
=====================
On most systems where you can run Python, the best way to install Sopel is to
install `pip <https://pypi.org/project/pip/>`_ and then ``pip install sopel``.

Arch users can install the ``sopel`` package from the [community] repository,
though new versions might take slightly longer to become available.

Failing both of those options, you can grab the latest tarball `from GitHub
<https://github.com/sopel-irc/sopel/releases/latest>`_ and follow the steps
for installing from the latest source below.

Latest source
=============
First, either clone the repository with ``git clone
git://github.com/sopel-irc/sopel.git`` or download a tarball `from GitHub
<https://github.com/sopel-irc/sopel/releases/latest>`_.

Note: Sopel requires Python 2.7.x or Python 3.3+ to run. On Python 2.7,
Sopel requires ``backports.ssl_match_hostname`` to be installed. Use
``pip install backports.ssl_match_hostname`` or
``yum install python-backports.ssl_match_hostname`` to install it, or download
and install it manually `from PyPI <https://pypi.org/project/backports.ssl_match_hostname>`_.

Note: Python 2.x is near end of life. Sopel will drop support in version 8.0.

In the source directory (whether cloned or from the tarball) run ``pip install
-e .``. You can then run ``sopel`` to configure and start the bot.

Database support
----------------
Sopel leverages SQLAlchemy to support the following database types: SQLite,
MySQL, PostgreSQL, MSSQL, Oracle, Firebird, and Sybase. By default Sopel will
use a SQLite database in the current configuration directory, but alternative
databases can be configured with the following config options: ``db_type``,
``db_filename`` (SQLite only), ``db_driver``, ``db_user``, ``db_pass``,
``db_host``, ``db_port``, and ``db_name``. You will need to manually install
any packages (system or ``pip``) needed to make your chosen database work.

**Note:** Plugins not updated since Sopel 7.0 was released *might* have
problems with database types other than SQLite (but many will work just fine).

Adding plugins
--------------
The easiest place to put new plugins is in ``~/.sopel/plugins``. Some newer
plugins are installable as packages; `search PyPI
<https://pypi.org/search/?q=%22sopel%22>`_ for these. Many more plugins
written by other users can be found using your favorite search engine.

Some older, unmaintained plugins are available in the
`sopel-extras <https://github.com/sopel-irc/sopel-extras>`_ repository, but of
course you can also write your own. A `tutorial <https://sopel.chat/tutorials/part-1-writing-plugins/>`_
for creating new plugins is available on Sopel's website.
API documentation can be found online at https://sopel.chat/docs/, or
you can create a local version by running ``make docs``.

Further documentation
---------------------

The `official website <https://sopel.chat/>`_ includes such valuable information
as a full listing of built-in `commands <https://sopel.chat/usage/commands/>`_,
`tutorials <https://sopel.chat/tutorials/>`_, `API documentation <https://sopel.chat/docs/>`_,
and other `usage information <https://sopel.chat/usage/>`_.

Questions?
----------

Join us in `#sopel <irc://irc.freenode.net/#sopel>`_ on Freenode.

Financial support
-----------------

We're thrilled that you want to support the project!

We have applied for access to organization-level sponsorship from GitHub. In
the interim, if you wish to contribute sooner, you are welcome to do so
through `Open Collective <https://opencollective.com/sopel>`_ or sponsor
Sopel's maintainer, `dgw <https://github.com/sponsors/dgw>`_, individually.

Any donations received will be used to cover infrastructure costs, such as our
domain name and hosting services. Our main project site is easily hosted by
`Netlify <https://www.netlify.com/>`_, but we are considering building a few
new features that would require more than static hosting. All project-related
`expenses <https://opencollective.com/sopel/expenses>`_ are tracked on our
Open Collective profile, for transparency.

.. |version| image:: https://img.shields.io/pypi/v/sopel.svg
:target: https://pypi.python.org/pypi/sopel
.. |build| image:: https://travis-ci.org/sopel-irc/sopel.svg?branch=master
:target: https://travis-ci.org/sopel-irc/sopel
.. |issues| image:: https://img.shields.io/github/issues/sopel-irc/sopel.svg
:target: https://github.com/sopel-irc/sopel/issues
.. |alerts| image:: https://img.shields.io/lgtm/alerts/g/sopel-irc/sopel.svg
:target: https://lgtm.com/projects/g/sopel-irc/sopel/alerts/
.. |coverage-status| image:: https://coveralls.io/repos/github/sopel-irc/sopel/badge.svg?branch=master
:target: https://coveralls.io/github/sopel-irc/sopel?branch=master
.. |license| image:: https://img.shields.io/pypi/l/sopel.svg
:target: https://github.com/sopel-irc/sopel/blob/master/COPYING