### Start and Login SoulSeekClient

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Instantiate and start the SoulSeekClient, connect to the server, and log in. This example also shows how to send a private message and then stop the client.

```python
import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.commands import PrivateMessageCommand

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())


```

--------------------------------

### Start and Login Client

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Create and start the client. Calling client.start() connects listening ports and the server. Then, perform a login and send a private message. Ensure to stop the client when done.

```python
import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.commands import PrivateMessageCommand

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())
```

--------------------------------

### Get User Status

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

This example demonstrates how to get a user's status by executing a command and waiting for a response. Set response=True to receive a return value.

```python
from aioslsk.user.model import UserStatus
from aioslsk.commands import GetUserStatusCommand

# Setting status to away
status, privileged = await client(
    GetUserStatusCommand('someone'), response=True)
```

--------------------------------

### GET /query

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Performs a query on shared directories.

```APIDOC
## GET /query

### Description
Performs a query on the shared_directories returning the matching items.

### Parameters
#### Query Parameters
- **query** (str) - Required - The search query.
- **username** (str) - Optional - The username to filter results.
- **excluded_search_phrases** (list) - Optional - Phrases to exclude.
```

--------------------------------

### SharesManager.start

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Asynchronously starts the manager, performing any necessary start-up actions after data loading and before network connection.

```APIDOC
## start

### Description
Optionally performs a start action on the manager. Gets called after loading the data but before connecting.
```

--------------------------------

### Get Recommendations Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve general recommendations.

```APIDOC
## Get Recommendations Command

### Description
Retrieves a list of general recommendations.

### Method
GET

### Endpoint
`/api/recommendations`

### Response
#### Success Response (200)
- **Recommendations** (object) - An object containing recommendations.

#### Response Example
```json
{
  "recommendations": [
    {
      "id": "rec1",
      "name": "General Recommendation 1"
    }
  ]
}
```
```

--------------------------------

### Create and Configure Settings

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Before starting the client, create a settings object and configure credentials. It is also recommended to configure a listening port and a downloads directory.

```python
from aioslsk.settings import Settings, CredentialsSettings

# Create default settings and configure credentials
settings: Settings = Settings(
    credentials=CredentialsSettings(
        username='my_user',
        password='Secret123'
    )
)
```

--------------------------------

### Manager Start/Stop Methods

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Methods for starting and stopping various manager components.

```APIDOC
## Manager Lifecycle Methods

### Description
Methods to control the lifecycle of various managers within the AIOSLSK system.

### Methods
- `aioslsk.base_manager.BaseManager.start()`
- `aioslsk.client.SoulSeekClient.start()`
- `aioslsk.shares.manager.SharesManager.start()`
- `aioslsk.tasks.BackgroundTask.start()`
- `aioslsk.tasks.Timer.start()`
- `aioslsk.transfer.manager.TransferManager.start()`
- `aioslsk.user.manager.UserManager.start()`
- `aioslsk.base_manager.BaseManager.stop()`
- `aioslsk.client.SoulSeekClient.stop()`
- `aioslsk.distributed.DistributedNetwork.stop()`
- `aioslsk.search.manager.SearchManager.stop()`
- `aioslsk.shares.manager.SharesManager.stop()`
- `aioslsk.transfer.manager.TransferManager.stop()`
- `aioslsk.user.manager.UserManager.stop()`
- `aioslsk.user.manager.UserTrackingManager.stop()`
```

--------------------------------

### Execute Commands with SoulSeekClient

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Examples demonstrating how to execute commands with and without waiting for a response from the server.

```python
from aioslsk.commands import GetUserStatusCommand 

status = await client.execute(
    GetUserStatusCommand(‘someuser’), reponse=True)
```

```python
from aioslsk.commands import JoinRoomCommand
await client.execute(JoinRoomCommand(‘cool room’))
```

--------------------------------

### Exporting and Importing Settings

Source: https://aioslsk.readthedocs.io/en/latest/SETTINGS.html

Examples of how to serialize the library settings to a JSON file and how to load them back into the application.

```APIDOC
## Exporting Settings

### Description
Serializes the current settings object to a JSON file using the pydantic-settings dump_model method.

### Request Example
```python
import json
from aioslsk.settings import Settings, CredentialsSettings

settings = Settings(
    credentials=CredentialsSettings(username='user', password='testpass')
)
settings_filename = 'my_settings.json'

with open(settings_filename, 'w') as fh:
    fh.write(settings.dump_model(mode='json'))
```

## Importing Settings

### Description
Reads a JSON file and initializes the Settings object with the loaded data.

### Request Example
```python
import json
from aioslsk.settings import Settings, CredentialsSettings

settings_filename = 'my_settings.json'

with open(settings_filename, 'r') as fh:
    py_settings = json.load(fh)

loaded_settings = Settings(**py_settings)
```
```

--------------------------------

### Configure Shared Directories with Settings

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Defines initial shared directories and their access modes within the client settings. Use this to set up your shares when the client starts.

```python
settings: Settings = Settings(
    credentials=CredentialsSettings(username='my_user', password='Secret123'),
    shares=SharesSettings(
        scan_on_start=True,
        directories=[
            SharedDirectorySettingEntry(
                'music/metal',
                share_mode=DirectoryShareMode.EVERYONE
            ),
            SharedDirectorySettingEntry(
                'music/punk',
                share_mode=DirectoryShareMode.FRIENDS
            ),
            SharedDirectorySettingEntry(
                'music/folk',
                share_mode=DirectoryShareMode.USERS,
                users=['secret guy']
            )
        ]
    )
)
```

--------------------------------

### Client Lifecycle Management

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Methods to start, stop, and manage the client connection state.

```APIDOC
## Client Lifecycle Methods

### start(connect=True)
Performs startup tasks including loading data, starting services, and optionally connecting to the network.
- **connect** (bool) - Optional - Whether to connect the network after startup.

### stop()
Stops the client, disconnects the network, cancels pending tasks, and saves caches.

### connect()
Initializes the network by connecting to the server and opening listening ports.

### login(client_version=157, minor_version=100)
Performs a logon to the server.
- **client_version** (int) - Optional - Client version number.
- **minor_version** (int) - Optional - Minor version number.
- **Raises** - AuthenticationError if login fails.
```

--------------------------------

### Implement Custom File Naming Strategy

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Provides an example of creating a custom NamingStrategy to organize downloaded files into directories based on the current date. This strategy is then added to the client's naming strategies.

```python
from datetime import datetime
import os
from aioslsk.naming import NamingStrategy, DefaultNamingStrategy

class DatetimeDirectoryStrategy(NamingStrategy):

    # Override the apply method
    def apply(self, remote_path: str, local_dir: str, local_filename: str) -> tuple[str, str]:
        current_datetime = datetime.now().strftime('%Y-%M-%d')
        return os.path.join(local_dir, current_datetime), local_filename

# Modify the strategy
client.shares_manager.naming_strategies = [
    DefaultNamingStrategy(),
    DatetimeDirectoryStrategy(),
]
```

--------------------------------

### Use Client with Context Manager

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

The client can be used with an async context manager, which automatically handles starting and stopping the client. This simplifies resource management.

```python
import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.commands import PrivateMessageCommand

async def main():
    async with SoulSeekClient(settings) as client:
        await client.login()
        # Send a private message
        await client.execute(PrivateMessageCommand('my_friend', 'Hi!'))

asyncio.run(main())
```

--------------------------------

### Perform Searches

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

The protocol implements network, room, and user searches. This example shows how to initiate each type of search request.

```python
from aioslsk.search.model import SearchRequest

global_request: SearchRequest = await client.searches.search('my query')
room_request: SearchRequest = await client.searches.search_room('cool_room', 'my room query')
user_request: SearchRequest = await client.searches.search_user('other_user', 'my user query')
```

--------------------------------

### Get Global Recommendations Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve global recommendations.

```APIDOC
## Get Global Recommendations Command

### Description
Retrieves a list of global recommendations.

### Method
GET

### Endpoint
`/api/recommendations/global`

### Response
#### Success Response (200)
- **Recommendations** (object) - An object containing global recommendations.

#### Response Example
```json
{
  "recommendations": [
    {
      "id": "global_rec1",
      "name": "Global Recommendation 1"
    }
  ]
}
```
```

--------------------------------

### Initiate File Download

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Starts a file download in the background. Requires importing Transfer and SearchRequest. Ensure a search is performed and a result is selected before initiating the download.

```python
from aioslsk.transfer.model import Transfer

search_request: SearchRequest = await client.searches.search('my query')
# Wait for a bit and get the first search result
await asyncio.sleep(5)
search_result: SearchResult = search_request.results[0]
# The following will attempt to start the download in the background
transfer: Transfer = await client.transfers.download(search_result.username, search_result.shared_items[0].filename)
```

--------------------------------

### Get Item Recommendations Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve recommendations for a specific item.

```APIDOC
## Get Item Recommendations Command

### Description
Retrieves a list of recommendations related to a specific item.

### Method
GET

### Endpoint
`/api/items/{item}/recommendations`

### Parameters
#### Path Parameters
- **item** (str) - Required - The identifier of the item for which to get recommendations.

### Response
#### Success Response (200)
- **list[Recommendation]** - A list of recommendation objects.

#### Response Example
```json
[
  {
    "id": "rec1",
    "name": "Recommended Item 1"
  },
  {
    "id": "rec2",
    "name": "Recommended Item 2"
  }
]
```
```

--------------------------------

### Manage Shared Directories Dynamically

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Shows how to add, update, scan, and remove shared directories on the fly. Use these methods to modify shares after the client has started.

```python
from aioslsk.shares.model import DirectoryShareMode

# Add a shared directory only shared with friends
shared_dir = client.shares.add_shared_directory(
    'my/shared/directory',
    share_mode=DirectoryShareMode.FRIENDS
)

# Update the shared directory
client.shares.update_shared_directory(
    shared_dir,
    share_mode=DirectoryShareMode.EVERYONE
)

# Scan the directory files and file attributes
await client.shares.scan_directory_files(shared_dir)
await client.shares.scan_directory_file_attributes(shared_dir)

# Scanning all current shared directories
await client.shares.scan()

# Removing a shared directory
client.shares.remove_shared_directory(shared_dir)
```

--------------------------------

### Configure Sharing Settings

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Configures sharing settings, including credentials, scanning on start, and specific shared directories with different access modes. Requires importing Settings, CredentialsSettings, SharesSettings, SharedDirectorySettingEntry, and DirectoryShareMode.

```python
from aioslsk.settings import (
    Settings,
    CredentialsSettings,
    SharesSettings,
    SharedDirectorySettingEntry,
)
from aioslsk.shares.model import DirectoryShareMode

# Configure credentials, configure to scan the shares on start, and set the
# desired shared directories
settings: Settings = Settings(
    credentials=CredentialsSettings(username='my_user', password='Secret123'),
    shares=SharesSettings(
        scan_on_start=True,
        directories=[
            SharedDirectorySettingEntry(
                'music/metal',
                share_mode=DirectoryShareMode.EVERYONE
            ),
            SharedDirectorySettingEntry(
                'music/punk',
                share_mode=DirectoryShareMode.FRIENDS
            ),
            SharedDirectorySettingEntry(
                'music/folk',
                share_mode=DirectoryShareMode.USERS,
                users=['secret guy']
            )
        ]
    )
)
```

--------------------------------

### Track User Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to start tracking a specific user.

```APIDOC
## TrackUserCommand

### Description
Initiates tracking of a specified user's activity.

### Attributes
- **username** (string) - The username of the user to track.

### Methods
- **send()**: Sends the command to the server.
- **build_expected_response()**: Constructs the expected response object.
- **handle_response()**: Processes the response from the server.
```

--------------------------------

### Register Event Listener

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Register callbacks for events using client.events.register. This example shows how to listen for the RoomJoinedEvent and print a message when a user joins a room.

```python
from aioslsk.events import RoomJoinedEvent

async def on_room_joined(event: RoomJoinedEvent):
    if not event.user:
        print(f"We have joined room {event.room.name}!")
    else:
        print(f"User {event.user.name} has joined room {event.room.name}!")

client.events.register(RoomJoinedEvent, on_room_joined)
```

--------------------------------

### Shares Settings

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Configuration for file sharing, including scan on start, download path, and directories.

```APIDOC
## Class aioslsk.settings.SharesSettings

### Description
Configuration for file sharing, including scan on start, download path, and directories.

### Parameters
- **scan_on_start** (bool) - Whether to scan for shared items on startup. Defaults to True.
- **download** (str) - The default download path for shared files. Defaults to '/home/docs/checkouts/readthedocs.org/user_builds/aioslsk/checkouts/latest/docs/source'.
- **directories** (list[SharedDirectorySettingEntry]) - A list of directories to share.

### Attributes
- **scan_on_start**: bool
- **download**: str
- **directories**: list[SharedDirectorySettingEntry]
```

--------------------------------

### Set User Status

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Commands are used to send requests to the server. This example shows how to set the user's status using the SetStatusCommand. The client can also be called directly to execute commands.

```python
from aioslsk.user.model import UserStatus
from aioslsk.commands import SetStatusCommand

# Setting status to away
await client.execute(SetStatusCommand(UserStatus.AWAY))

# Setting status to online
await client(SetStatusCommand(UserStatus.AWAY))
```

--------------------------------

### Get Item Similar Users Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve users similar to those who liked a specific item.

```APIDOC
## Get Item Similar Users Command

### Description
Retrieves a list of users who are similar to users that liked a specific item.

### Method
GET

### Endpoint
`/api/items/{item}/similar_users`

### Parameters
#### Path Parameters
- **item** (str) - Required - The identifier of the item.

### Response
#### Success Response (200)
- **list[User]** - A list of user objects.

#### Response Example
```json
[
  {
    "username": "user1"
  },
  {
    "username": "user2"
  }
]
```
```

--------------------------------

### GET /transfers/uploading

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Returns all transfers that are currently uploading or attempting to start.

```APIDOC
## GET /transfers/uploading

### Description
Returns all transfers that are currently uploading or an attempt is made to start uploading.

### Method
GET

### Response
#### Success Response (200)
- **transfers** (list[Transfer]) - List of active uploading transfers
```

--------------------------------

### GET /is_directory_shared

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Checks if a directory is currently shared.

```APIDOC
## GET /is_directory_shared

### Description
Checks if a directory is already a shared directory by checking the absolute path of that directory.

### Parameters
#### Query Parameters
- **directory** (str) - Required - The directory path.

### Response
#### Success Response (200)
- **bool** - True if shared, false otherwise.
```

--------------------------------

### GET /filesize

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves the file size of a shared item.

```APIDOC
## GET /filesize

### Parameters
#### Query Parameters
- **shared_item** (SharedItem) - Required - The item to check.

### Response
#### Success Response (200)
- **int** - The file size.
```

--------------------------------

### GET /shared_directory

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves information about a specific shared directory.

```APIDOC
## GET /shared_directory

### Description
Calculates the absolute path of given directory and looks for the matching SharedDirectory instance.

### Parameters
#### Query Parameters
- **directory** (str) - Required - The directory path.

### Response
#### Success Response (200)
- **SharedDirectory** - The matching SharedDirectory instance.
```

--------------------------------

### Initialize SoulSeekClient with Shares Cache

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Demonstrates initializing the SoulSeekClient with custom settings and a SharesShelveCache. Ensure the data directory for the cache exists.

```python
from aioslsk.client import SoulSeekClient
from aioslsk.settings import CredentialsSettings, SharesSettings
from aioslsk.cache import SharesShelveCache
import asyncio

async def main():
    settings = SoulSeekClient.Settings(
        credentials=CredentialsSettings(username='my_user', password='Secret123'),
        shares=SharesSettings(
            scan_on_start=False,
            directories=[
                # Some directories you wish to share
            ]
        )
    )

    cache = SharesShelveCache(data_directory='documents/shares_cache/')

    async with SoulSeekClient(settings, shares_cache=cache) as client:
        await client.login()

        # If there were shared items stored in the cache this will output
        # the total amount of directories and files shared
        dir_count, file_count = client.shares.get_stats()
        print(f"currently sharing {dir_count} directories and {file_count} files")

        # Manually write the cache to disk
        client.shares.write_cache()

asyncio.run(main())
```

--------------------------------

### GET /transfers/speed

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves current download and upload speeds.

```APIDOC
## GET /transfers/speed

### Description
Returns current download and upload speeds in bytes/second.

### Method
GET

### Response
#### Success Response (200)
- **download_speed** (float) - Current download speed
- **upload_speed** (float) - Current upload speed
```

--------------------------------

### GetItemRecommendations (Code 111)

Source: https://aioslsk.readthedocs.io/en/latest/MESSAGES.html

Get recommendations based on an interest.

```APIDOC
## GetItemRecommendations (Code 111)

### Description
Get a list of recommendations based on a single interest.

### Request Body
- **item** (string) - Required

### Response
- **item** (string)
- **recommendations** (array[Recommendation])
```

--------------------------------

### Configure Shared Directories

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Import necessary settings classes to configure file sharing.

```python
from aioslsk.settings import (
    Settings,
    CredentialsSettings,
    SharesSettings,
    SharedDirectorySettingEntry,
)
from aioslsk.shares.model import DirectoryShareMode
```

--------------------------------

### GetUserStatus (Code 7)

Source: https://aioslsk.readthedocs.io/en/latest/MESSAGES.html

Get the current status of a user.

```APIDOC
## GetUserStatus (Code 7)

### Description
Get the user status. The server automatically sends updates for users added via AddUser or those in the same room.

### Parameters
#### Request Body
- **username** (string) - Required - The username to query

### Response
#### Success Response (200)
- **username** (string) - Username
- **status** (uint32) - Status code
- **privileged** (boolean) - Privileged status
```

--------------------------------

### Get User Stats

Source: https://aioslsk.readthedocs.io/en/latest/_sources/SOULSEEK.rst.txt

Retrieves the statistics for a given user.

```APIDOC
## Get User Stats

### Description
Retrieves the statistics for a given user.

### Message
:ref:`GetUserStats`

### Checks
* If the user does not exist in the ``users`` list:
  1. :ref:`GetUserStats`
     * ``username`` : name of the user for which stats were requested
     * all stats set to 0

### Actions
  1. :ref:`GetUserStats`
     * ``username`` : name of the user for which stats were requested
     * stats of the user for which stats were requested
```

--------------------------------

### Import settings from JSON

Source: https://aioslsk.readthedocs.io/en/latest/SETTINGS.html

Reads a JSON file and initializes the Settings object with the loaded data.

```python
import json
from aioslsk.settings import Settings, CredentialsSettings

settings_filename = 'my_settings.json'

with open(settings_filename, 'r') as fh:
    py_settings = json.load(fh)

loaded_settings = Settings(**py_settings)
```

--------------------------------

### Get Statistics

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves the total count of shared directories and files.

```APIDOC
## GET /stats

### Description
Gets the total amount of shared directories and files.

### Method
GET

### Endpoint
/stats

### Response
#### Success Response (200)
- **directory_count** (int) - The total number of shared directories.
- **file_count** (int) - The total number of shared files.

#### Response Example
{
  "directory_count": 50,
  "file_count": 200
}
```

--------------------------------

### Configuration Parameters

Source: https://aioslsk.readthedocs.io/en/latest/_sources/SETTINGS.rst.txt

Overview of available configuration settings for searches, transfers, and debugging.

```APIDOC
## Configuration Parameters

### Searches
- **searches.receive.store_amount** (integer) - Amount of received searches to store in the client (Default: 500)
- **searches.send.store_results** (boolean) - Whether to store search results internally (Default: true)
- **searches.send.request_timeout** (integer) - Timeout for sent search requests (0 = keep indefinitely) (Default: 0)
- **searches.send.wishlist_request_timeout** (integer) - Timeout for sent wishlist requests (0 = keep indefinitely, -1 = use server interval) (Default: -1)
- **searches.wishlist** (array[object]) - List of wishlist items
  - **query** (string) - Wishlist item search query
  - **enabled** (boolean) - Whether this query is enabled or disabled (Default: true)

### Transfers
- **transfers.limits.upload_slots** (integer) - Maximum amount of simultaneously uploads (Default: 2)
- **transfers.report_interval** (float) - Transfer progress reporting interval in seconds (Default: 0.250)

### Debug
- **debug.search_for_parent** (boolean) - Toggle searching for a distributed parent (Default: true)
- **debug.user_ip_overrides** (map[string, string]) - Mapping of username and IP addresses
- **debug.log_connection_count** (boolean) - Periodically log the amount of current connections (Default: false)
```

--------------------------------

### Get Peer Address Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve the address of a peer.

```APIDOC
## Get Peer Address Command

### Description
Retrieves the network address and port of a specified user (peer).

### Method
GET

### Endpoint
`/api/users/{username}/address`

### Parameters
#### Path Parameters
- **username** (str) - Required - The username of the peer.

### Response
#### Success Response (200)
- **tuple[str, int, Optional[int]]** - A tuple containing the IP address, port, and an optional connection type.

#### Response Example
```json
{
  "ip_address": "192.168.1.100",
  "port": 12345,
  "connection_type": 0
}
```
```

--------------------------------

### Request and Listen for Item Recommendations

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Register an event handler for ItemRecommendationsEvent and use GetItemRecommendationsCommand to fetch recommendations.

```python
from aioslsk.events import ItemRecommendationsEvent
from aioslsk.commands import GetItemRecommendationsCommand

async def on_item_recommendations(event: ItemRecommendationsEvent):
    if len(event.recommendations) > 0:
        print(f"Best recommendation for item {event.item} : {event.recommendations[0]}")

client.events.register(ItemRecommendationsEvent, on_item_recommendations)

await client(GetItemRecommendationsCommand('funny jokes'))
```

--------------------------------

### GetItemSimilarUsers (Code 112)

Source: https://aioslsk.readthedocs.io/en/latest/MESSAGES.html

Get similar users based on an interest.

```APIDOC
## GetItemSimilarUsers (Code 112)

### Description
Get a list of similar users based on a single interest.

### Request Body
- **item** (string) - Required

### Response
- **item** (string)
- **usernames** (array[string])
```

--------------------------------

### GetUserList (Code 67)

Source: https://aioslsk.readthedocs.io/en/latest/MESSAGES.html

Gets a list of all users on the server. Deprecated.

```APIDOC
## GetUserList (Code 67)

### Description
Gets a list of all users on the server.

### Parameters
#### Request Body
- No parameters

### Response
#### Success Response (200)
- **users** (array[string])
- **users_status** (array[uint32])
- **users_stats** (array[UserStats])
- **users_slots_free** (array[uint32])
- **users_countries** (array[string])
```

--------------------------------

### Get User Status

Source: https://aioslsk.readthedocs.io/en/latest/_sources/SOULSEEK.rst.txt

Retrieves the current online status of a user.

```APIDOC
## Get User Status

### Description
Retrieves the current online status of a user.

### Message
:ref:`GetUserStatus`

### Checks
* If the user does not exist in the ``users`` list:
  1. :ref:`GetUserStatus`
     * ``username`` : name of the user for which status was requested
     * ``status`` : ``UserStatus.OFFLINE``

### Actions
  1. :ref:`GetUserStatus`
     * ``username`` : name of the user for which status was requested
     * ``status`` : ``status`` of the user for which status was requested
```

--------------------------------

### Message 110: Get Similar Users

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves a list of similar users.

```APIDOC
## MESSAGE 110

### Description
Get a list of similar users.

### Response
- **users** (list[SimilarUser]) - List of similar user objects.
```

--------------------------------

### Manage Transfer States (Pause, Queue, Abort)

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Demonstrates pausing, queuing, and aborting transfers. Paused transfers can be resumed with queue(), while aborted transfers are restarted from the beginning. Requires importing Transfer.

```python
from aioslsk.transfer.model import Transfer

# The following will attempt to start the download in the background
transfer: Transfer = await client.transfers.download('someuser', 'somefile.mp3')

# Pause the download wait and requeue
await client.transfers.pause(transfer)
await asyncio.sleep(5)
await client.transfers.queue(transfer)

# Abort and requeue
await client.transfers.abort(transfer)
await asyncio.sleep(5)
await client.transfers.queue(transfer)
```

--------------------------------

### SharesManager.load_from_settings

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Loads shared directories from settings, updating existing ones, adding new ones, and removing non-existent ones.

```APIDOC
## load_from_settings

### Description
Loads the shared directories from the settings. Existing directories will be updated, non-existing directories added, directories that no longer exist will be removed.
```

--------------------------------

### GET /transfers/lookup

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Lookup a specific transfer by username, remote path, and direction.

```APIDOC
## GET /transfers/lookup

### Description
Lookup transfer by username, remote_path and transfer direction.

### Method
GET

### Parameters
#### Query Parameters
- **username** (str) - Required - Username of the transfer
- **remote_path** (str) - Required - Full remote path of the transfer
- **direction** (TransferDirection) - Required - Direction of the transfer (upload / download)

### Response
#### Success Response (200)
- **transfer** (Transfer) - The matching transfer object
```

--------------------------------

### Get Similar Users Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve a list of similar users.

```APIDOC
## Get Similar Users Command

### Description
Retrieves a list of similar users.

### Method
GET

### Endpoint
`/api/users/similar`

### Response
#### Success Response (200)
- **list[tuple[User, int]]** - A list of tuples, where each tuple contains a User object and an integer representing similarity.

#### Response Example
```json
[
  {
    "user": {"username": "user1"},
    "similarity": 95
  },
  {
    "user": {"username": "user2"},
    "similarity": 90
  }
]
```
```

--------------------------------

### Implement Custom File Naming Strategy

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Extend NamingStrategy to create custom file naming logic, such as organizing files into date-based directories. Ensure to override the apply method.

```python
from datetime import datetime
import os
from aioslsk.naming import NamingStrategy, DefaultNamingStrategy

class DatetimeDirectoryStrategy(NamingStrategy):

    # Override the apply method
    def apply(self, remote_path: str, local_dir: str, local_filename: str) -> tuple[str, str]:
        current_datetime = datetime.now().strftime('%Y-%M-%d')
        return os.path.join(local_dir, current_datetime), local_filename

# Modify the strategy
client.shares_manager.naming_strategies = [
    DefaultNamingStrategy(),
    DatetimeDirectoryStrategy(),
]

```

--------------------------------

### SoulSeekClient Initialization

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Initializes the SoulSeek client with necessary settings and optional caches or factories.

```APIDOC
## SoulSeekClient Initialization

### Description
Creates a new instance of the SoulSeekClient, which acts as a facade for various managers.

### Parameters
- **settings** (Settings) - Required - Configuration settings for the client.
- **shares_cache** (Optional[SharesCache]) - Optional - Cache for shared files.
- **transfer_cache** (Optional[TransferCache]) - Optional - Cache for transfer data.
- **executor_factory** (Optional[ExecutorFactory]) - Optional - Factory for creating executors.
- **event_bus** (Optional[EventBus]) - Optional - Event bus for communication.
```

--------------------------------

### Create Directory Reply

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Lists directory data, including files within that directory, as a response to a directory request. Returns an empty list if the directory does not exist.

```APIDOC
## POST /create_directory_reply

### Description
Lists directory data as a response to a directory request. This will not contain any information about subdirectories, only the files within that directory. If the directory does not exist, an empty list is returned.

### Method
POST

### Endpoint
/create_directory_reply

### Parameters
#### Request Body
- **remote_directory** (str) - Required - The remote path of the directory.

### Response
#### Success Response (200)
- **directory_data** (list[_DirectoryData_]) - A list of directory data entries. Empty if the directory is not shared or does not exist.

#### Response Example
{
  "directory_data": [
    {
      "name": "report.docx",
      "path": "/shared/docs/report.docx"
    }
  ]
}
```

--------------------------------

### Get User Interests Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve the interests of a specific user.

```APIDOC
## GetUserInterestsCommand

### Description
Retrieves the list of interests associated with a given user.

### Attributes
- **username** (string) - The username of the user whose interests are to be retrieved.

### Methods
- **send()**: Sends the command to the server.
- **build_expected_response()**: Constructs the expected response object.
- **handle_response()**: Processes the response from the server.
```

--------------------------------

### Configure SoulSeekClient Settings

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Create a settings object for the SoulSeekClient, ensuring the credentials section is configured. It's recommended to also configure a listening port and downloads directory.

```python
from aioslsk.settings import Settings, CredentialsSettings

# Create default settings and configure credentials
settings: Settings = Settings(
    credentials=CredentialsSettings(
        username='my_user',
        password='Secret123'
    )
)


```

--------------------------------

### Get User Interests

Source: https://aioslsk.readthedocs.io/en/latest/_sources/SOULSEEK.rst.txt

Retrieves the interests and hated interests for a specified user.

```APIDOC
## GetUserInterests

### Description
Retrieves the interests and hated interests for a specified user.

### Actors
* ``user``: User for whom the interests were requested.

### Input Checks
* If the ``username`` is empty: continue.

### Checks
* If the ``user`` does not exist:
  1. Respond with `:ref:`GetUserInterests` containing:
     * ``username``: username of the user for whom interests were requested.
     * ``interests``: empty list.
     * ``hated_interests``: empty list.

### Actions
1. Respond with `:ref:`GetUserInterests` containing:
   * ``username``: username of the user for whom interests were requested.
   * ``interests``: list of user's interests.
   * ``hated_interests``: list of user's hated interests.
```

--------------------------------

### SharesManager.load_data

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Asynchronously loads data for the manager during client startup, before any connections are established.

```APIDOC
## load_data

### Description
Load the data for the manager. This method gets called during client client start-up before any connection is made.
```

--------------------------------

### AdminMessage (MESSAGE_ID: 66)

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Message sent by the admin, for example, when the server is going down.

```APIDOC
## AdminMessage

### Description
Sent by the admin to notify users of server events like maintenance or shutdown.

### Response Parameters
- **message** (str)
```

--------------------------------

### Initialize Client with Shares Cache

Source: https://aioslsk.readthedocs.io/en/latest/_sources/USAGE.rst.txt

Initializes the SoulSeekClient using settings that include a shares cache configured with the shelve module. Requires importing asyncio, SoulSeekClient, SharesShelveCache, Settings, CredentialsSettings, and SharesSettings.

```python
import asyncio
from aioslsk.client import SoulSeekClient
from aioslsk.shares.cache import SharesShelveCache
from aioslsk.settings import (Settings, CredentialsSettings, SharesSettings)

async def main():
    settings: Settings = Settings(

```

--------------------------------

### AIOSLSK L Components

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Details on classes, attributes, and methods in AIOSLSK starting with 'L'.

```APIDOC
## L Components

### Classes
- **LeaveRoom** (class in aioslsk.protocol.messages)
  - **LeaveRoom.Request** (class in aioslsk.protocol.messages)
  - **LeaveRoom.Response** (class in aioslsk.protocol.messages)
- **LeaveRoomCommand** (class in aioslsk.commands)
- **ListeningConnection** (class in aioslsk.network.connection)
- **ListeningConnectionErrorMode** (class in aioslsk.network.network)
- **ListeningConnectionFailedError**
- **ListeningSettings** (class in aioslsk.settings)
- **Login** (class in aioslsk.protocol.messages)
  - **Login.Request** (class in aioslsk.protocol.messages)
  - **Login.Response** (class in aioslsk.protocol.messages)

### Attributes
- **last_queue_attempt** (aioslsk.transfer.model.Transfer attribute)
- **last_state** (aioslsk.network.network.WatchdogContext attribute)
- **last_upload_request_attempt** (aioslsk.transfer.model.Transfer attribute)
- **lease_duration** (aioslsk.settings.UpnpSettings attribute)
- **level** (aioslsk.protocol.messages.BranchLevel.Request attribute)
  - (aioslsk.protocol.messages.DistributedBranchLevel.Request attribute)
- **liked** (aioslsk.settings.InterestsSettings attribute)
- **limits** (aioslsk.settings.NetworkSettings attribute)
  - (aioslsk.settings.TransfersSettings attribute)
- **listening** (aioslsk.settings.NetworkSettings attribute)
- **listening_connections** (aioslsk.network.network.Network attribute)
- **local_path** (aioslsk.transfer.model.Transfer attribute)
- **locked_directories** (aioslsk.events.UserSharesReplyEvent attribute)
  - (aioslsk.protocol.messages.PeerSharesReply.Request attribute)
- **locked_results** (aioslsk.protocol.messages.PeerSearchReply.Request attribute)
  - (aioslsk.search.model.SearchResult attribute)
- **log_connection_count** (aioslsk.settings.DebugSettings attribute)
- **logged_in_at** (aioslsk.session.Session attribute)

### Methods
- **load_data()** (aioslsk.base_manager.BaseManager method)
  - (aioslsk.shares.manager.SharesManager method)
  - (aioslsk.transfer.manager.TransferManager method)
- **load_from_settings()** (aioslsk.shares.manager.SharesManager method)
- **load_speed_limits()** (aioslsk.network.network.Network method)
- **login()** (aioslsk.client.SoulSeekClient method)
```

--------------------------------

### AIOSLSK K Components

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Details on classes, attributes, and constants in AIOSLSK starting with 'K'.

```APIDOC
## K Components

### Classes
- **KeepDirectoryStrategy** (class in aioslsk.naming)
- **Kicked** (class in aioslsk.protocol.messages)
  - **Kicked.Response** (class in aioslsk.protocol.messages)
- **KickedEvent** (class in aioslsk.events)

### Attributes
- **key** (aioslsk.protocol.primitives.Attribute attribute)

### Constants
- **KEY_SIZE** (in module aioslsk.protocol.obfuscation)
```

--------------------------------

### SharesManager.create_directory

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Asynchronously ensures that the specified directory exists.

```APIDOC
## create_directory

### Description
Ensures the passed directory exists.

### Parameters
* **absolute_path** (_str_)
```

--------------------------------

### GET /peer/connection

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves an existing peer connection or creates a new one if necessary.

```APIDOC
## GET /peer/connection

### Description
Gets a peer connection for the given username. It will first try to re-use an existing connection, otherwise it will create a new connection.

### Parameters
#### Query Parameters
- **username** (str) - Required - username of the peer
- **typ** (str) - Optional - Type of connection to create or reuse

### Response
#### Success Response (200)
- **PeerConnection** (object) - A PeerConnection instance
```

--------------------------------

### GET /transfers/finished

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Returns a list of transfers in a finalized state (COMPLETE, ABORTED, FAILED).

```APIDOC
## GET /transfers/finished

### Description
Returns a complete list of transfers that are in a finalized state (COMPLETE, ABORTED, FAILED).

### Method
GET

### Response
#### Success Response (200)
- **transfers** (list[Transfer]) - List of finalized transfers
```

--------------------------------

### Command Methods

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

A list of available command methods for interacting with the aioslsk protocol, including room management, user statistics, and recommendations.

```APIDOC
## Command Methods

### Description
These methods are part of the `aioslsk.commands` module and are used to execute various actions within the Soulseek network.

### Methods
- `CheckPrivilegesCommand.handle_response()`
- `DropRoomMembershipCommand.handle_response()`
- `GetGlobalRecommendationsCommand.handle_response()`
- `GetItemRecommendationsCommand.handle_response()`
- `GetItemSimilarUsersCommand.handle_response()`
- `GetPeerAddressCommand.handle_response()`
- `GetRecommendationsCommand.handle_response()`
- `GetRoomListCommand.handle_response()`
- `GetSimilarUsersCommand.handle_response()`
- `GetUserInterestsCommand.handle_response()`
- `GetUserStatsCommand.handle_response()`
- `GetUserStatusCommand.handle_response()`
- `GrantRoomMembershipCommand.handle_response()`
- `GrantRoomOperatorCommand.handle_response()`
- `JoinRoomCommand.handle_response()`
- `LeaveRoomCommand.handle_response()`
- `PeerGetDirectoryContentCommand.handle_response()`
- `PeerGetSharesCommand.handle_response()`
- `PeerGetUserInfoCommand.handle_response()`
- `RevokeRoomMembershipCommand.handle_response()`
- `RevokeRoomOperatorCommand.handle_response()`
- `RoomMessageCommand.handle_response()`
- `TogglePrivateRoomInvitesCommand.handle_response()`
- `TrackUserCommand.handle_response()`
```

--------------------------------

### ConnectToPeer API

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Manages the initiation of connections between peers in the network.

```APIDOC
## ConnectToPeer

### Description
Initiates a connection to a specific peer.

### Request
- **ConnectToPeer.Request** (class) - Contains connection details.

### Response
- **ConnectToPeer.Response** (class) - Contains the result of the connection attempt.
```

--------------------------------

### Peer Get Shares Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve shared items from a peer user.

```APIDOC
## PeerGetSharesCommand

### Description
Retrieves a list of items shared by a specified peer user.

### Attributes
- **username** (string) - The username of the peer user.

### Methods
- **send()**: Sends the command to the server.
- **build_expected_response()**: Constructs the expected response object.
- **handle_response()**: Processes the response from the server.
```

--------------------------------

### Request Item Recommendations

Source: https://aioslsk.readthedocs.io/en/latest/USAGE.html

Register an event handler for ItemRecommendationsEvent to process recommendations. Use GetItemRecommendationsCommand to request recommendations for a specific item.

```python
from aioslsk.events import ItemRecommendationsEvent
from aioslsk.commands import GetItemRecommendationsCommand

async def on_item_recommendations(event: ItemRecommendationsEvent):
    if len(event.recommendations) > 0:
        print(f"Best recommendation for item {event.item} : {event.recommendations[0]}")

client.events.register(ItemRecommendationsEvent, on_item_recommendations)

await client(GetItemRecommendationsCommand('funny jokes'))

```

--------------------------------

### Peer Get User Info Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve information about a peer user.

```APIDOC
## PeerGetUserInfoCommand

### Description
Retrieves detailed information about a specified peer user.

### Attributes
- **username** (string) - The username of the peer user.

### Methods
- **send()**: Sends the command to the server.
- **build_expected_response()**: Constructs the expected response object.
- **handle_response()**: Processes the response from the server.
```

--------------------------------

### Sharing Configuration Parameters

Source: https://aioslsk.readthedocs.io/en/latest/_sources/SETTINGS.rst.txt

Configuration settings for file sharing directories and download management.

```APIDOC
## Sharing Configuration

### Parameters
- **shares.download** (string) - Directory to which files will be downloaded to. Default: <current working directory>
- **shares.directories** (array) - List of shared directories (SharedDirectorySettingEntry). Default: <empty>
- **shares.scan_on_start** (boolean) - Schedule a scan as soon as the client starts up (after reading the cache). Default: true
```

--------------------------------

### Message 111: Get Item Recommendations

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves recommendations based on a specific interest item.

```APIDOC
## MESSAGE 111

### Description
Get a list of recommendations based on a single interest.

### Request Body
- **item** (str) - Required - The interest item.

### Response
- **item** (str) - The requested item.
- **recommendations** (list[Recommendation]) - List of recommendations.
```

--------------------------------

### Get Shared Directories for User

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Retrieves a list of shared directories associated with a specific user.

```APIDOC
## GET /shared_directories/{username}

### Description
Gets the shared directories for a specific user.

### Method
GET

### Endpoint
/shared_directories/{username}

### Parameters
#### Path Parameters
- **username** (str) - Required - The username whose shared directories are to be retrieved.

### Response
#### Success Response (200)
- **shared_directories** (list[_SharedDirectory_]) - A list of shared directories belonging to the user.

#### Response Example
{
  "shared_directories": [
    {
      "name": "public_docs",
      "path": "/shared/public_docs"
    }
  ]
}
```

--------------------------------

### Logging Utility

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Details on the process method within the ConnectionLoggerAdapter.

```APIDOC
## process() Method

### Description
Processes log data for a connection.

### Method
process()

### Class
aioslsk.log_utils.ConnectionLoggerAdapter
```

--------------------------------

### Settings and Configuration

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Attributes related to library settings.

```APIDOC
## report_interval (attribute)

### Description
Specifies the interval for reporting transfer status.

### Context
- aioslsk.settings.TransfersSettings

### Method
(Method not specified in source)

### Endpoint
(Endpoint not specified in source)

### Parameters
(Parameters not specified in source)

### Request Example
(Request example not specified in source)

### Response
(Response not specified in source)
```

--------------------------------

### Peer Get Directory Content Command

Source: https://aioslsk.readthedocs.io/en/latest/API.html

Command to retrieve the content of a peer user's directory.

```APIDOC
## PeerGetDirectoryContentCommand

### Description
Retrieves the content of a specified directory belonging to a peer user.

### Attributes
- **username** (string) - The username of the peer user.
- **directory** (string) - The path to the directory.

### Methods
- **send()**: Sends the command to the server.
- **build_expected_response()**: Constructs the expected response object.
- **handle_response()**: Processes the response from the server.
```

--------------------------------

### Configuration and Settings

Source: https://aioslsk.readthedocs.io/en/latest/genindex.html

Information regarding configuration settings and strategies used within the aioslsk library.

```APIDOC
## Configuration and Settings

### Classes
- **DebugSettings** (class in aioslsk.settings)
- **DefaultNamingStrategy** (class in aioslsk.naming)

### Attributes
- **debug** (aioslsk.settings.Settings attribute)
- **description** (aioslsk.settings.UserInfoSettings attribute)
- **directories** (aioslsk.settings.SharesSettings attribute)
```