Newsbin Pro Client

NewsbinproClient is the main client for communicating with Newsbin Pro.

class newsbinpro_client.newsbinproclient.NewsbinProClient(server_address: str, port: int, password: str, on_connected_callback: Callable[[], None] = None, on_disconnected_callback: Callable[[], None] = None, on_data_sent: Callable[[str], None] = None, on_data_received: Callable[[str], None] = None, on_received_list_item: Callable[[str], None] = None, log_level: int = 20)

Bases: object

A client for connecting to a NewsbinPro server for remote control.

async add_group_filter(group_name: str) → bool

Adds a group or a group of groups if a topic is selected. The topic is expanded into the list of current groups. These groups are used by “Load” and “Search” to specify what groups to look into.

Parameters:

group_name – The name of the group filter to add.

Returns:

A boolean indicating whether the group filter was successfully added.

async assemble_download(item_id: int) → bool

Parameters:

item_id – The identifier of the download to be assembled.

Returns:

A boolean value indicating whether the assembly of the download was successful.

async clear_downloads() → bool

Clears the current list of downloads.

Sends a command to clear all download entries and checks the response status code to confirm the action was successful.

Returns:

True if the list of downloads is successfully cleared, False otherwise.

async clear_filters(clear: bool) → bool

Clears the existing size filters and groups.

Parameters:

clear – A boolean value indicating whether to clear all filters (True) or not (False).

Returns:

A boolean value representing whether the command succeeded (True) or failed (False).

async clear_group() → bool

Clear a group

Returns:

Returns True if the group is successfully cleared, False otherwise.

async clear_loaded() → bool

Clears the loaded list.

Returns:

Returns True if the command was successfully executed, False otherwise.

async close() → bool

Closes the Newsbin Pro application. No further communication is possible after this call.

Returns:

True if the command execution was successful and the status code is OK, False otherwise

async connect(timeout: int = 30)

Establishes a connection to the NewsbinPro server.

If authentication is required, it attempts to authenticate using the provided password.

Parameters:

timeout (int) – The maximum time (in seconds) to wait for the connection. Default is 30 seconds.

Raises:

Exception – If authentication with the server fails.

property connected

Returns:

Returns True if the client is connected, otherwise, returns False.

async delete_from_group(group_id: int) → bool

Delete from a group.

Parameters:

group_id – The identifier of the group to be deleted.

Returns:

A boolean indicating whether the deletion was successful.

async disconnect()

Disconnects the client by sending the quit command to the server. Handles the client disconnection event and disposes of the connection.

Returns:

None

async download_file_from_files(file_name: str, item_id: int) → bool

Parameters:

• file_name – The name of the file where the content will be saved.

• item_id – The identifier for the file to be downloaded.

Returns:

True if the file was successfully downloaded, False otherwise.

async download_from_loaded(item_id: int) → bool

Download a file from the loaded list.

Parameters:

item_id – The identifier of the item to be downloaded.

Returns:

True if the download operation was successful, False otherwise.

async download_from_wish(item_id: int) → bool

Parameters:

item_id – The unique identifier for the wish download request.

Returns:

Boolean indicating whether the download operation was successful.

async download_move_bottom(item_id: int) → bool

Moves a download item to the bottom of the download queue.

Parameters:

item_id – The identifier of the download item to be moved.

Returns:

Returns True if the operation was successful, otherwise False.

async download_move_down(item_id: int) → bool

Parameters:

item_id – The unique identifier of the item to move down in the download list.

Returns:

A boolean indicating whether the command to move the download down was successfully executed.

async download_move_top(item_id: int) → bool

Parameters:

item_id – Identifier of the download to be moved to the top of the queue.

Returns:

Boolean indicating whether the operation was successful.

async download_move_up(item_id: int) → bool

Parameters:

item_id – Identifier of the download to be moved up in the queue.

Returns:

True if the operation was successful, False otherwise.

async download_stream_from_files(stream: BinaryIO, item_id: int) → bool

Parameters:

• stream – The binary stream where the downloaded file content will be written.

• item_id – The identifier of the file to be downloaded.

Returns:

Returns True if the file was successfully downloaded, otherwise False.

async enable_filters(enabled: bool) → bool

Enable/Disable filter.

Parameters:

enabled – Boolean value indicating whether to enable (True) or disable (False) filters.

Returns:

Boolean value indicating whether the operation was successful.

async find_in_downloads(text: str) → bool

Parameters:

text – The text to search for in the download list.

Returns:

A boolean indicating whether the search operation was successful (True if the status code equals OK, False otherwise).

async find_loaded(text: str) → List[GroupFileSet]

Finds matching items in the loaded list.

Parameters:

text – The text used to search and filter the loaded file sets.

Returns:

A list of GroupFileSet instances representing the loaded file sets that match the search criteria.

static get_auth_string(password: str, password_salt: str) → str

Parameters:

• password – The original password string that needs to be hashed.

• password_salt – A salt string to be appended to the password for added security.

Returns:

A hexadecimal string representation of the MD5 hash of the concatenated password and salt.

async get_bandwidth_limiter_state()

Sends a command to check the state of the bandwidth limiter and returns its status.

Returns:

True if the bandwidth limiter is on, False otherwise.

async get_downloads_count() → int

Sends a command to retrieve the total downloads count.

Returns:

The number of downloads.

Return type:

int

async get_downloads_list(start_index: int, end_index: int) → List[DownloadFileSet]

Parameters:

• start_index – The starting index for the range of downloads to retrieve.

• end_index – The ending index for the range of downloads to retrieve.

Returns:

A list of DownloadFileSet objects representing the downloads in the specified range.

async get_files_count() → int

Asynchronously retrieves the count of files.

Returns:

The count of files as an integer.

async get_files_list(start_index: int, end_index: int) → List[FilesFileSet]

Parameters:

• start_index – The starting index for retrieving the list of files.

• end_index – The ending index for retrieving the list of files.

Returns:

A list of FilesFileSet objects representing the retrieved files.

async get_loaded_count() → int

Gets the number of loaded items.

Returns:

The total count of loaded items.

async get_nzb_from_loaded(min_index: int, max_index: int) → bool

Parameters:

• min_index – The minimum index of the NZB to retrieve.

• max_index – The maximum index of the NZB to retrieve.

Returns:

True if the NZB was successfully retrieved, False otherwise.

async get_paused_state()

Sends a pause command to check whether the system is in a paused state.

Returns:

A boolean indicating if the system is in a paused state. True if the system is paused, False otherwise.

async get_response() → Response

Reads a line asynchronously and returns a Response object containing the line read.

Returns:

An instance of the Response class containing the data from the asynchronously read line.

async get_status() → NewsbinProStatus

Retrieves the status of NewsbinPro by sending a status command and aggregating the response into a NewsbinProStatus object.

Returns:

An instance of NewsbinProStatus containing the aggregated status data.

async get_wish_count() → int

Returns:

The count of wishes as an integer received from sending the WishCount command.

async get_wish_list(start_index: int, end_index: int) → List[WishFileSet]

Parameters:

• start_index – The starting index for the wish list items to retrieve.

• end_index – The ending index for the wish list items to retrieve.

Returns:

A list of WishFileSet objects representing the retrieved wish list items.

async hide_old(hide: bool) → bool

Enable/Disable the “hide old” filter

Parameters:

hide – A boolean value indicating whether to hide old filters. If True, old filters will be hidden; otherwise, they will not.

Returns:

A boolean value indicating whether the command to hide old filters was successfully executed.

async list_children(gog_name: str) → ListResponse

Lists all children of a particular parent topic.

Parameters:

gog_name – The name of the group or object whose children need to be listed.

Returns:

A ListResponse containing the children of the specified group or object.

async list_children_details(gog_name: str) → ListResponse

Lists all children details of a particular parent topic.

Parameters:

gog_name – The name of the group or object whose children details need to be listed.

Returns:

A ListResponse containing the details of the children for the specified group or object.

async list_filters() → ListResponse

Lists all filters

Returns:

A ListResponse object containing the available filters.

async list_gogs() → ListResponse

Lists all group topics (parents)

Returns:

The response containing the list of Gogs.

Return type:

ListResponse

async list_group_of_groups_with_children() → GroupOfGroupsTree

Lists groups and their respective child groups into a tree structure.

Returns:

GroupOfGroupsTree object representing the hierarchy of groups and their children.

async list_groups() → ListResponse

Lists all subscribed groups.

Returns:

A ListResponse object containing the details of all groups.

async list_loaded(start_index: int, end_index: int) → List[GroupFileSet]

List the loaded items.

Parameters:

• start_index – The starting index from which to begin retrieving the loaded file sets.

• end_index – The ending index at which to stop retrieving the loaded file sets.

Returns:

A list of GroupFileSet objects representing the loaded file sets within the specified range.

async list_servers() → ListResponse

Sends a command to list all available servers and returns the response.

Returns:

An object of type ListResponse containing the list of servers.

async load_group(min_age: int, max_age: int) → int

Load a group. To load the last 10 days of records for instance the min_age would be 10 and the max_age would be zero. It counts backwards. load_group(20, 10) would load posts from 20 days ago to 10 days ago.

Parameters:

• min_age – The minimum age for filtering the group.

• max_age – The maximum age for filtering the group.

Returns:

The result of the command, representing the number of entries loaded.

async lock_downloads() → bool

Sends a command to lock the downloads and returns whether the operation was successful.

Returns:

True if the downloads were successfully locked, False otherwise

async mark_all_old() → bool

Sends a command to mark all items as old.

Returns:

True if the operation was successful, False otherwise.

async mark_old(item_id: int) → bool

Tag the files as “Old” both in the display list and on disk.

Parameters:

item_id – The unique identifier of the filter to be marked as old.

Returns:

True if the filter was successfully marked as old, otherwise False.

async pause_download(item_id: int) → bool

Pauses an active download by its identifier.

Parameters:

item_id – The unique identifier of the download to be paused.

Returns:

True if the pause command was successfully executed, False otherwise.

async read_binary(bytes_to_read: int) → bytes

Parameters:

bytes_to_read – The number of bytes to read from the binary stream.

Returns:

A bytes object containing the data read from the stream. Returns an empty bytes object if no reader is available.

async read_line_async()

Reads a single line of data asynchronously using the reader and processes it.

Returns:

A single line of data read from the reader, stripped of whitespace and decoded as a UTF-8 string.

Return type:

str

Raises:

AttributeError – If the _reader attribute is not set.

async resume_download(item_id: int) → bool

Resumes a paused download for the specified download ID.

Parameters:

item_id – The unique identifier of the download to be resumed.

Returns:

True if the download was successfully resumed, False otherwise.

async save() → bool

Saves the current configuration file.

Returns:

A boolean indicating whether the save operation was successful.

async search_internet(min_age: int, max_age: int, search_string: str) → bool

Searches using the search server, the groups listed using “AddGroupFilter” or all groups if no groups have been added. It loads each group in turn and only saves the items in memory that match the filter string and size filters. These matched items are added to the display buffer and become accessible using the “Loaded” interface. The min age/max age set how many day in the past to search from. So, a setting of 100 and 0 means “from 100 days ago to 0 days ago( Now)”.

Parameters:

• min_age – The minimum age to include in the search criteria.

• max_age – The maximum age to include in the search criteria.

• search_string – The term or phrase to search for on the internet.

Returns:

A boolean indicating whether the search operation was successful.

async search_local(min_age: int, max_age: int, search_string: str) → bool

Searches the groups listed using “AddGroupFilter” or all groups if no groups have been added. It loads each group in turn and only saves the items in memory that match the filter string and size filters. These matched items are added to the display buffer and become accessible using the “Loaded” interface. The min age/max age set how many day in the past to search from. So, a setting of 100 and 0 means “from 100 days ago to 0 days ago( Now)”. Only finds records from groups that have actually had headers downloaded.

Parameters:

• min_age – The minimum age to filter the search results.

• max_age – The maximum age to filter the search results.

• search_string – The string to search for in the local data.

Returns:

A boolean indicating whether the search operation was successful.

async send_command(command: Command, arg1: str = '', arg2: str = '', arg3: str = '') → Response

Parameters:

• command – The command to be sent to the external system.

• arg1 – First argument to be appended to the command, optional.

• arg2 – Second argument to be appended to the command, optional.

• arg3 – Third argument to be appended to the command, optional.

Returns:

A Response object containing the result from the external system.

async send_command_without_response(command: Command)

Parameters:

command – The command to be sent, represented as an instance of the Command class.

Returns:

None. This method does not return a value.

async send_list_command(command: Command, arg1: str = '', arg2: str = '') → ListResponse

Parameters:

• command – The command to be sent, represented as a Command object.

• arg1 – Optional string argument to append to the command.

• arg2 – Optional string argument to append to the command.

Returns:

A ListResponse object containing the parsed response data.

async send_long_command(command: Command, arg1='', arg2='')

Parameters:

• command – The command to be sent, represented as a Command object.

• arg1 – An optional argument to be included in the command, defaults to an empty string.

• arg2 – An optional second argument to be included in the command, defaults to an empty string.

Returns:

An integer value parsed from the response message if the status code is OK, otherwise returns 0.

async set_bandwidth_limiter_state(state: bool)

Parameters:

state – A boolean value indicating the desired state of the bandwidth limiter. True to turn it on, False to turn it off.

Returns:

A boolean indicating whether the operation to set the bandwidth limiter state was successful.

async set_filter_age(hours: int) → bool

Sets the maximum age of the sets in the display buffer.

Parameters:

hours – The age limit for the filter in hours.

Returns:

A boolean value indicating if the filter age was successfully set.

async set_filter_max_size(max_size: int) → bool

Sets the maximum size filter for when search or group loading is performed.

Parameters:

max_size – The maximum size to set for the filter as an integer.

Returns:

A boolean indicating whether the operation to set the maximum size was successful.

async set_filter_min_size(min_size: int) → bool

Sets the minimum size filter for when search or group loading is performed.

Parameters:

min_size (int) – The minimum size value to set for the filter.

Returns:

A boolean indicating whether the command to set the filter minimum size was successful.

Return type:

bool

async set_filter_profile(profile_name: str) → bool

Set filter profile.

Parameters:

profile_name – The name of the filter profile to set.

Returns:

A boolean indicating whether the operation was successful.

async set_paused_state(state: bool)

Parameters:

state – A boolean value indicating the desired paused state. True to set the state to paused, False to set it to unpaused.

Returns:

A boolean indicating whether the operation was successful. Returns True if the pause state was successfully set to the desired value, otherwise False.

async set_text_filter(text: str) → bool

Sets the current text filter. Text quoting is optional (but recommended). An empty string will clear the text filter.

Parameters:

text – The text to set as the filter.

Returns:

A boolean value indicating whether setting the text filter was successful or not.

async sort_downloads_list(column: int, ascending: bool) → bool

Parameters:

• column – The index of the column by which the downloads list should be sorted.

• ascending – A boolean indicating whether the sorting should be in ascending order. If False, sorting will be in descending order.

Returns:

A boolean indicating whether the operation was successful (True) or not (False).

async sort_loaded(column: int, ascending: bool) → bool

Sorts the loaded items according to the specified column.

Parameters:

• column – The index of the column to sort.

• ascending – A boolean indicating the sort order. If True, sort in ascending order; if False, sort in descending order.

Returns:

A boolean indicating whether the sorting operation was successful.

async unlock_downloads() → bool

Sends a command to unlock downloads and checks the response status.

Returns:

True if the downloads were successfully unlocked, False otherwise.

async update() → bool

Sends an update command.

Returns:

True if the update command was successful (status is OK), otherwise False.

async upload_nzb_file(file_name: str) → bool

Parameters:

file_name – The path to the NZB file to be uploaded.

Returns:

A boolean indicating whether the NZB file was successfully uploaded.

async upload_nzb_stream(file_name: str, stream: BinaryIO, size: int) → bool

Parameters:

• file_name – The name of the NZB file being uploaded.

• stream – A binary stream containing the contents of the NZB file.

• size – The size of the NZB file in bytes.

Returns:

A boolean value indicating whether the upload operation was successful.

async write_binary(buffer: bytes) → bool

Parameters:

buffer – The binary data to write, passed as a bytes object.

Returns:

A boolean value indicating whether the operation was successful. Returns True if the data was written successfully, otherwise False.

async write_line_async(command: str)

Parameters:

command – The string command to write to the underlying writer, appended with a newline character.

Returns:

None. This is an asynchronous method that writes the command and optionally executes a callback.