def iter_catalog(self, identifier=None, params=None, request_kwargs=None):
"""A generator that returns queued or running tasks.
:type identifier: str
:param identifier: (optional) Item identifier.
:type params: dict
:param params: (optional) Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:type request_kwargs: dict
:param request_kwargs: (optional) Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:rtype: collections.Iterable[CatalogTask]
"""
params = {} if not params else params
params.update({
'identifier': identifier,
'catalog': 1,
'summary': 0,
'history': 0
})
c = Catalog(self, request_kwargs)
yield from c.iter_tasks(params)
def get_tasks(self, identifier=None, params=None, request_kwargs=None):
"""Get a list of all tasks meeting all criteria.
The list is ordered by submission time.
:type identifier: str
:param identifier: (optional) The item identifier, if provided
will return tasks for only this item filtered by
other criteria provided in params.
:type params: dict
:param params: (optional) Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:type request_kwargs: dict
:param request_kwargs: (optional) Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:rtype: List[CatalogTask]
"""
params = dict() if not params else params
c = Catalog(self, request_kwargs)
if 'history' not in params:
params['history'] = 1
if 'catalog' not in params:
params['catalog'] = 1
return c.get_tasks(identifier=identifier, params=params)
def submit_task(self, identifier, cmd, comment=None, priority=None, data=None,
request_kwargs=None):
"""Submit an archive.org task.
:type identifier: str
:param identifier: Item identifier.
:type cmd: str
:param cmd: Task command to submit, see
`supported task commands
<https://archive.org/services/docs/api/tasks.html#supported-tasks>`_.
:type comment: str
:param comment: (optional) A reasonable explanation for why the
task is being submitted.
:type priority: int
:param priority: (optional) Task priority from 10 to -10
(default: 0).
:type data: dict
:param data: (optional) Extra POST data to submit with
the request. Refer to `Tasks API Request Entity
<https://archive.org/services/docs/api/tasks.html#request-entity>`_.
:type request_kwargs: dict
:param request_kwargs: (optional) Keyword arguments to be used in
:meth:`requests.sessions.Session.post` request.
:rtype: :class:`requests.Response`
"""
c = Catalog(self, request_kwargs)
r = c.submit_task(identifier, cmd, comment=comment, priority=priority, data=data)
return r
def submit_task(self, identifier, cmd, comment=None, priority=None, data=None,
headers=None, reduced_priority=None, request_kwargs=None):
"""Submit an archive.org task.
:type identifier: str
:param identifier: Item identifier.
:type cmd: str
:param cmd: Task command to submit, see
`supported task commands
<https://archive.org/services/docs/api/tasks.html#supported-tasks>`_.
:type comment: str
:param comment: (optional) A reasonable explanation for why the
task is being submitted.
:type priority: int
:param priority: (optional) Task priority from 10 to -10
(default: 0).
:type data: dict
:param data: (optional) Extra POST data to submit with
the request. Refer to `Tasks API Request Entity
<https://archive.org/services/docs/api/tasks.html#request-entity>`_.
:type headers: dict
:param headers: (optional) Add additional headers to request.
:type reduced_priority: bool
:param reduced_priority: (optional) 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.
:type request_kwargs: dict
:param request_kwargs: (optional) Keyword arguments to be used in
:meth:`requests.sessions.Session.post` request.
:rtype: :class:`requests.Response`
"""
headers = dict() if not headers else headers
if reduced_priority is not None:
headers.update({'X-Accept-Reduced-Priority': '1'})
c = Catalog(self, request_kwargs)
r = c.submit_task(identifier, cmd,
comment=comment,
priority=priority,
data=data,
headers=headers)
return r
def get_tasks_summary(self, identifier=None, params=None, request_kwargs=None):
"""Get the total counts of catalog tasks meeting all criteria,
organized by run status (queued, running, error, and paused).
:type identifier: str
:param identifier: (optional) Item identifier.
:type params: dict
:param params: (optional) Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:type request_kwargs: dict
:param request_kwargs: (optional) Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:rtype: dict
"""
c = Catalog(self, request_kwargs)
return c.get_summary(identifier=identifier, params=params)
def get_tasks(self,
identifier=None,
task_ids=None,
task_type=None,
params=None,
config=None,
verbose=None,
request_kwargs=None):
"""Get tasks from the Archive.org catalog. ``internetarchive`` must be configured
with your logged-in-* cookies to use this function. If no arguments are provided,
all queued tasks for the user will be returned.
:type identifier: str
:param identifier: (optional) The Archive.org identifier for which to retrieve
tasks for.
:type task_ids: int or str
:param task_ids: (optional) The task_ids to retrieve from the Archive.org catalog.
:type task_type: str
:param task_type: (optional) The type of tasks to retrieve from the Archive.org
catalog. The types can be either "red" for failed tasks, "blue"
for running tasks, "green" for pending tasks, "brown" for paused
tasks, or "purple" for completed tasks.
:type params: dict
:param params: (optional) The URL parameters to send with each request sent to the
Archive.org catalog API.
:type config: dict
:param secure: (optional) Configuration options for session.
:type verbose: bool
:param verbose: (optional) Set to ``True`` to retrieve verbose information for
each catalog task returned. verbose is set to ``True`` by default.
:returns: A set of :class:`CatalogTask` objects.
"""
request_kwargs = {} if not request_kwargs else request_kwargs
_catalog = Catalog(self,
identifier=identifier,
task_ids=task_ids,
params=params,
config=config,
verbose=verbose,
request_kwargs=request_kwargs)
if task_type:
return eval('_catalog.{0}_rows'.format(task_type.lower()))
else:
return _catalog.tasks
def iter_history(self, identifier, params=None, request_kwargs=None):
"""A generator that returns completed tasks.
:type identifier: str
:param identifier: (optional) Item identifier.
:type params: dict
:param params: (optional) Query parameters, refer to
`Tasks API
<https://archive.org/services/docs/api/tasks.html>`_
for available parameters.
:type request_kwargs: dict
:param request_kwargs: (optional) Keyword arguments to be used in
:meth:`requests.sessions.Session.get` request.
:rtype: collections.Iterable[CatalogTask]
"""
params = dict() if not params else params
params.update(dict(identifier=identifier, catalog=0, summary=0, history=1))
c = Catalog(self, request_kwargs)
for j in c.iter_tasks(params):
yield j
def get_tasks_api_rate_limit(self, cmd='derive.php', request_kwargs=None):
c = Catalog(self, request_kwargs)
r = c.get_rate_limit(cmd=cmd)
return r