upsies.trackers.base.tracker

Abstract base class for all tracker-specific stuff

Classes

class upsies.trackers.base.tracker.TrackerBase(options=None)

Bases: ABC

Base class for tracker-specific operations, e.g. uploading

Parameters:

options (dict-like) – User configuration options for this tracker, e.g. authentication details, announce URL, etc

abstract property TrackerJobs

Subclass of TrackerJobsBase

abstract property TrackerConfig

Subclass of TrackerConfigBase

cli_arguments = {}

CLI argument definitions (see CommandBase.cli_arguments)

rules = None

Sequence of TrackerRuleBase subclasses or None

For convenience, this may also be a ModuleType that provides TrackerRuleBase subclasses.

abstract property name

Lower-case tracker name abbreviation for internal use

abstract property label

User-facing tracker name abbreviation

abstract property torrent_source_field

Torrents for this tracker get a source field with this value

This is usually the same as label.

setup_howto_template = 'Nobody has written a setup howto yet.'

Step-by-step guide that explains how to make your first upload

Note

This MUST be a class attribute and not a property.

The following placeholders can be used in f-string format:

• howto - Howto instance

• tracker - TrackerBase subclass

• executable - Name of the executable that runs the application

classmethod generate_setup_howto()

Fill in any placeholders in setup_howto_template

property options

Configuration options provided by the user

This is the dict-like object from the initialization argument of the same name.

attach_task(coro, callback=None)

Run awaitable coro in background task

Parameters:

• coro – Any awaitable

• callback –

  Callable that is called with the task after coro returned

  Warning

  callback must handle any exception raised by the task or it will be ignored.

async await_tasks()

Wait for all awaitables passed to attach_task()

async login(**credentials)

End user session by calling _login, which must be implemented by the subclass

Set is_logged_in to True or False. Emit logged_in signal on success.

Any keyword arguments are passed on to _login(), e.g. to provide a 2FA one-time password.

_login() should raise TfaRequired to get called again with a tfa_otp keyword argument. The tfa_otp value will be from a user prompt that asks for a 2FA one-time password. (See login_job().)

Raises:

• errors.RequestError – on failure

• errors.TfaRequired – if login failed due to missing second factor

async still_logged_in()

Return whether we have a valid user session stored in cookies_filepath

If no cookies_filepath is specified, return None.

Otherwise, catch RequestError from confirm_logged_in() to check if we are logged in.

If we are not logged in, call delete_cookies_filepath(), emit the login_failed signal and return False.

If we are logged in, emit the logged_in signal and return True.

async logout(*, force=False)

End user session by calling _logout, which must be implemented by the subclass

Set is_logged_in to False and emit logged_out signal, even if the logout request fails for some reason.

If a cookies_filepath is provided, do nothing unless force is True.

Raises:

errors.RequestError – on failure

abstractmethod async confirm_logged_in()

Check if we are logged in by doing a website request

This method is called by login() to make sure _login() succeeded. It is also called by still_logged_in(), which is used check if a stored user session is still working or if a new session must be started (e.g. because the cookie expired).

Raises:

errors.RequestError – if we are not logged in

property is_logged_in

Whether a user session is active

This is a boolean flag that is set by login() and logout().

property cookies_filepath

User-defined file path that stores login session cookie(s) or None if no such file is specified

Subclasses must include this in requests made to the tracker website if the tracker implementation uses traditional user sesssions via the website for submissions.

If the tracker implementation uses an API, cookies should not be used in requests and this property can be ignored.

delete_cookies_filepath()

Delete cookies_filepath if it is provided and exists

abstractmethod async get_announce_url()

Get announce URL from options or tracker website

Warning

You should expect that login() was called first when implementing this method and raise RuntimeError if is_logged_in is False.

Raises:

errors.RequestError – on any kind of failure

calculate_piece_size = None

staticmethod that takes a torrent’s content size and returns the corresponding piece size

If this is None, the default implementation is used.

calculate_piece_size_min_max = None

staticmethod that takes a torrent’s content size and returns the corresponding allowed minimum and maximum piece sizes

If this is None, the default implementation is used.

abstractmethod async upload(tracker_jobs)

Upload torrent and other metadata from jobs

Parameters:

tracker_jobs (TrackerJobsBase) – TrackerJobs instance

property signal

Signal instance with the following signals:

warning

Emitted when warn() is called. Registered callbacks get the provided warning argument.

error

Emitted when error() is called. Registered callbacks get the provided error argument.

exception

Emitted when exception() is called. Registered callbacks get the provided exception argument.

logging_in

Emitted by login() when login is attempted. Registered callbacks get no arguments.

login_failed

Emitted by login() when login failed. Registered callbacks get a RequestError exception.

logged_in

Emitted by login() when login succeeded. Registered callbacks get no arguments.

logging_out

Emitted by logout() when logout is attempted. Registered callbacks get no arguments.

logout_failed

Emitted by logout() when logout failed. Registered callbacks get a RequestError exception.

logged_out

Emitted by logout() when logout succeeded. Registered callbacks get no arguments.

warn(warning)

Emit warning signal (see signal)

Emit a warning for any non-critical issue that the user can choose to ignore or fix.

error(error)

Emit error signal (see signal)

Emit an error for any critical but expected issue that can’t be recovered from (e.g. I/O error).

exception(exception)

Emit exception signal (see signal)

Emit an exception for any critical and unexpected issue that should be reported as a bug.