=======
aioslsk
=======
aioslsk is a Python library for the SoulSeek protocol built on top of asyncio.
Supported Python versions are currently 3.9 - 3.13
You can find the full documentation `here <http://aioslsk.readthedocs.io/>`_
Installation
============
.. code-block:: shell
pip install aioslsk
Quick Start
===========
Starting the client and sending a private message:
.. code-block:: python
import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.commands import PrivateMessageCommand
from aioslsk.settings import Settings, CredentialsSettings
# Create default settings and configure credentials
settings: Settings = Settings(
credentials=CredentialsSettings(
username='my_user',
password='Secret123'
)
)
async def main():
client: SoulSeekClient = SoulSeekClient(settings)
await client.start()
await client.login()
# Send a private message
await client.execute(PrivateMessageCommand('my_friend', 'Hi!'))
await client.stop()
asyncio.run(main())
Development
===========
Install poetry_ and setup the project dependencies by running:
.. code-block:: shell
poetry install
A tool is available to start the client for debugging purposes (try out commands to the server, ...):
1. Create a ``settings.json`` file containing valid credentials in the ``tools/debug/`` directory (or pass a path using ``--settings``). To generate a simple settings file:
.. code-block:: shell
poetry run python -m aioslsk.settings generate -u "Hello" -p "World" > tools/debug/settings.json
2. To start the REPL run:
.. code-block:: shell
# Reads from tools/debug/settings.json
poetry run python -m tools.debug.debug_mode
# Reads from specific file
poetry run python -m tools.debug.debug_mode --settings ~/custom_settings.json
3. Run an example command (the ``aioslsk.commands`` module is aliased to the ``cmds`` variable):
.. code-block:: python
await client(cmds.GetPeerAddressCommand('some user'), response=True)
4. To close the REPL execute ``exit()`` or press ``Ctrl+Z``
Optionally the script takes a ``--cache-dir`` that will read/write the transfer and shares cache from the given directory
Building the documentation
--------------------------
.. code-block:: shell
cd docs/
poetry run make html
Running Tests
-------------
Running all tests:
.. code-block:: shell
poetry run pytest tests/
Running all tests with code coverage report:
.. code-block:: shell
poetry run pytest --cov=aioslsk --cov-report term-missing tests/
Mock Server
~~~~~~~~~~~
A mock server implementation is available for testing, to start the server run:
.. code-block:: shell
# By default the server listens on port 2416
poetry run python -m tests.e2e.mock.server
# Specifying multiple listening ports
poetry run python -m tests.e2e.mock.server --port 2416 2242
Configure the hostname or IP of the server in your client and connect. If such configuration is not possible you can add an entry to the ``hosts`` file of your system. For example:
::
127.0.0.1 server.slsknet.org
Use ``--help`` to get a list of available options.
Dependencies
------------
The package uses several dependencies:
* mutagen_ : library used for extracting audio metadata
* aiofiles_ : asyncio library for filesystem management
* async-upnp-client_ : library for managing UPnP configuration
* pydantic-settings_ : library for managing settings
* async-timeout_ : library providing timeout class
.. _poetry: https://python-poetry.org/
.. _mutagen: https://github.com/quodlibet/mutagen
.. _aiofiles: https://github.com/Tinche/aiofiles
.. _async-upnp-client: https://github.com/StevenLooman/async_upnp_client
.. _pydantic-settings: https://docs.pydantic.dev/latest/concepts/pydantic_settings/
.. _async-timeout: https://github.com/aio-libs/async-timeout
Raw data
{
"_id": null,
"home_page": "https://github.com/JurgenR/aioslsk/",
"name": "aioslsk",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.9",
"maintainer_email": null,
"keywords": "soulseek, p2p, async",
"author": "JurgenR",
"author_email": "1249228+JurgenR@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/d1/df/c693f398a714080e860f72655a2152e853c6c99af7077857330f676e2d65/aioslsk-1.4.1.tar.gz",
"platform": null,
"description": "=======\naioslsk\n=======\n\naioslsk is a Python library for the SoulSeek protocol built on top of asyncio.\n\nSupported Python versions are currently 3.9 - 3.13\n\nYou can find the full documentation `here <http://aioslsk.readthedocs.io/>`_\n\nInstallation\n============\n\n.. code-block:: shell\n\n pip install aioslsk\n\n\nQuick Start\n===========\n\nStarting the client and sending a private message:\n\n.. code-block:: python\n\n import asyncio\n from aioslsk.client import SoulSeekClient\n from aioslsk.commands import PrivateMessageCommand\n from aioslsk.settings import Settings, CredentialsSettings\n\n # Create default settings and configure credentials\n settings: Settings = Settings(\n credentials=CredentialsSettings(\n username='my_user',\n password='Secret123'\n )\n )\n\n async def main():\n client: SoulSeekClient = SoulSeekClient(settings)\n\n await client.start()\n await client.login()\n\n # Send a private message\n await client.execute(PrivateMessageCommand('my_friend', 'Hi!'))\n\n await client.stop()\n\n asyncio.run(main())\n\n\nDevelopment\n===========\n\nInstall poetry_ and setup the project dependencies by running:\n\n.. code-block:: shell\n\n poetry install\n\n\nA tool is available to start the client for debugging purposes (try out commands to the server, ...):\n\n1. Create a ``settings.json`` file containing valid credentials in the ``tools/debug/`` directory (or pass a path using ``--settings``). To generate a simple settings file:\n\n .. code-block:: shell\n\n poetry run python -m aioslsk.settings generate -u \"Hello\" -p \"World\" > tools/debug/settings.json\n\n2. To start the REPL run:\n\n .. code-block:: shell\n\n # Reads from tools/debug/settings.json\n poetry run python -m tools.debug.debug_mode\n # Reads from specific file\n poetry run python -m tools.debug.debug_mode --settings ~/custom_settings.json\n\n3. Run an example command (the ``aioslsk.commands`` module is aliased to the ``cmds`` variable):\n\n .. code-block:: python\n\n await client(cmds.GetPeerAddressCommand('some user'), response=True)\n\n4. To close the REPL execute ``exit()`` or press ``Ctrl+Z``\n\nOptionally the script takes a ``--cache-dir`` that will read/write the transfer and shares cache from the given directory\n\n\nBuilding the documentation\n--------------------------\n\n.. code-block:: shell\n\n cd docs/\n poetry run make html\n\n\nRunning Tests\n-------------\n\nRunning all tests:\n\n.. code-block:: shell\n\n poetry run pytest tests/\n\nRunning all tests with code coverage report:\n\n.. code-block:: shell\n\n poetry run pytest --cov=aioslsk --cov-report term-missing tests/\n\n\nMock Server\n~~~~~~~~~~~\n\nA mock server implementation is available for testing, to start the server run:\n\n.. code-block:: shell\n\n # By default the server listens on port 2416\n poetry run python -m tests.e2e.mock.server\n # Specifying multiple listening ports\n poetry run python -m tests.e2e.mock.server --port 2416 2242\n\nConfigure the hostname or IP of the server in your client and connect. If such configuration is not possible you can add an entry to the ``hosts`` file of your system. For example:\n\n::\n\n 127.0.0.1 server.slsknet.org\n\n\nUse ``--help`` to get a list of available options.\n\nDependencies\n------------\n\nThe package uses several dependencies:\n\n* mutagen_ : library used for extracting audio metadata\n* aiofiles_ : asyncio library for filesystem management\n* async-upnp-client_ : library for managing UPnP configuration\n* pydantic-settings_ : library for managing settings\n* async-timeout_ : library providing timeout class\n\n.. _poetry: https://python-poetry.org/\n.. _mutagen: https://github.com/quodlibet/mutagen\n.. _aiofiles: https://github.com/Tinche/aiofiles\n.. _async-upnp-client: https://github.com/StevenLooman/async_upnp_client\n.. _pydantic-settings: https://docs.pydantic.dev/latest/concepts/pydantic_settings/\n.. _async-timeout: https://github.com/aio-libs/async-timeout\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "Asyncio based SoulSeek client",
"version": "1.4.1",
"project_urls": {
"Documentation": "https://readthedocs.org/projects/aioslsk/",
"Homepage": "https://github.com/JurgenR/aioslsk/",
"Repository": "https://github.com/JurgenR/aioslsk/"
},
"split_keywords": [
"soulseek",
" p2p",
" async"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e27f335865807b870ee28695692ab458f2b9cd22f100c9a99e11e1dc606f1250",
"md5": "a3c980544861c9b9fb90bcddca84de95",
"sha256": "b59ece7f04790f6d75402e02290e84d7eabb01d36a58826f6e45516ba1c5408e"
},
"downloads": -1,
"filename": "aioslsk-1.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a3c980544861c9b9fb90bcddca84de95",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.9",
"size": 117872,
"upload_time": "2024-10-20T18:07:43",
"upload_time_iso_8601": "2024-10-20T18:07:43.660898Z",
"url": "https://files.pythonhosted.org/packages/e2/7f/335865807b870ee28695692ab458f2b9cd22f100c9a99e11e1dc606f1250/aioslsk-1.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d1dfc693f398a714080e860f72655a2152e853c6c99af7077857330f676e2d65",
"md5": "192117e50e53cb4988788d554985e292",
"sha256": "e1fa783e4e10953f87846ae2bc0084fea57bf87aa3e45432f063368b981cc9dc"
},
"downloads": -1,
"filename": "aioslsk-1.4.1.tar.gz",
"has_sig": false,
"md5_digest": "192117e50e53cb4988788d554985e292",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.9",
"size": 103574,
"upload_time": "2024-10-20T18:07:45",
"upload_time_iso_8601": "2024-10-20T18:07:45.251788Z",
"url": "https://files.pythonhosted.org/packages/d1/df/c693f398a714080e860f72655a2152e853c6c99af7077857330f676e2d65/aioslsk-1.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 18:07:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "JurgenR",
"github_project": "aioslsk",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "aioslsk"
}
JSON
