def get_tasks(
self,
identifier: str = "",
params: dict | None = None,
request_kwargs: Mapping | None = None) -> set[catalog.CatalogTask]:
"""Get a list of all tasks meeting all criteria.
The list is ordered by submission time.
:param identifier: The item identifier, if provided
will return tasks for only this item filtered by
other criteria provided in params.
:param params: Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:param request_kwargs: Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:returns: A set of all tasks meeting all criteria.
"""
params = params or {}
if 'history' not in params:
params['history'] = 1
if 'catalog' not in params:
params['catalog'] = 1
return set(
catalog.Catalog(self,
request_kwargs).get_tasks(identifier=identifier,
params=params))
def iter_catalog(
self,
identifier: str | None = None,
params: dict | None = None,
request_kwargs: Mapping | None = None
) -> Iterable[catalog.CatalogTask]:
"""A generator that returns queued or running tasks.
:param identifier: Item identifier.
:param params: Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:param request_kwargs: Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:returns: An iterable of queued or running CatalogTasks.
"""
params = params or {}
params.update({
'identifier': identifier,
'catalog': 1,
'summary': 0,
'history': 0
})
c = catalog.Catalog(self, request_kwargs)
yield from c.iter_tasks(params)
def submit_task(
self,
identifier: str,
cmd: str,
comment: str = '',
priority: int = 0,
data: dict | None = None,
headers: dict | None = None,
reduced_priority: bool = False,
request_kwargs: Mapping | None = None) -> requests.Response:
"""Submit an archive.org task.
:param identifier: Item identifier.
:param cmd: Task command to submit, see
`supported task commands
<https://archive.org/services/docs/api/tasks.html#supported-tasks>`_.
:param comment: A reasonable explanation for why the
task is being submitted.
:param priority: Task priority from 10 to -10
(default: 0).
:param data: Extra POST data to submit with
the request. Refer to `Tasks API Request Entity
<https://archive.org/services/docs/api/tasks.html#request-entity>`_.
:param headers: Add additional headers to request.
:param reduced_priority: Submit your derive at a lower priority.
This option is helpful to get around rate-limiting.
Your task will more likey be accepted, but it might
not run for a long time. Note that you still may be
subject to rate-limiting. This is different than
``priority`` in that it will allow you to possibly
avoid rate-limiting.
:param request_kwargs: Keyword arguments to be used in
:meth:`requests.sessions.Session.post` request.
:returns: :class:`requests.Response`
"""
headers = headers or {}
if reduced_priority:
headers.update({'X-Accept-Reduced-Priority': '1'})
return catalog.Catalog(self,
request_kwargs).submit_task(identifier,
cmd,
comment=comment,
priority=priority,
data=data,
headers=headers)
def get_tasks_summary(self,
identifier: str = "",
params: dict | None = None,
request_kwargs: Mapping | None = None) -> dict:
"""Get the total counts of catalog tasks meeting all criteria,
organized by run status (queued, running, error, and paused).
:param identifier: Item identifier.
:param params: Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:param request_kwargs: Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:returns: Counts of catalog tasks meeting all criteria.
"""
return catalog.Catalog(self, request_kwargs).get_summary(
identifier=identifier, params=params)
def get_tasks_api_rate_limit(self,
cmd: str = 'derive.php',
request_kwargs: dict | None = None):
return catalog.Catalog(self, request_kwargs).get_rate_limit(cmd=cmd)