Files
witness-fracture/.venv/lib/python3.12/site-packages/internetarchive/__pycache__/api.cpython-312.pyc
T

348 lines
20 KiB
Plaintext
Raw Normal View History

2025-06-23 17:55:02 -05:00
Ë
’»Yh„Oãó—dZddlmZddlmZddlmZmZmZddlZddl m
Z
ddl m Z m
Z
mZmZmZmZddl mZdd lmZ d dd
„Z d dd „Z d dd „Z d dd
„Z d dd„Z d d!d„Z d" d#d„Z d$ d%d„Z d& d'd„Z d( d)d„Zd*d„Z d+d„Z!y),zº
internetarchive.api
~~~~~~~~~~~~~~~~~~~
This module implements the Internetarchive API.
:copyright: (C) 2012-2024 by Internet Archive.
:license: AGPL 3, see LICENSE for more details.
é)Ú annotations)Úgetpass)ÚIterableÚMappingÚMutableMappingN)ÚRetry)ÚauthÚcatalogÚfilesÚitemÚsearchÚsession)Úconfig)ÚAuthenticationErrorcó:—tj||xsd||«S)aFReturn a new :class:`ArchiveSession` object. The :class:`ArchiveSession`
object is the main interface to the ``internetarchive`` lib. It allows you to
persist certain parameters across tasks.
:param config: A dictionary used to configure your session.
:param config_file: A path to a config file used to configure your session.
:param debug: To be passed on to this session's method calls.
:param http_adapter_kwargs: Keyword arguments that
:py:class:`requests.adapters.HTTPAdapter` takes.
:returns: To persist certain parameters across tasks.
Usage:
>>> from internetarchive import get_session
>>> config = {'s3': {'access': 'foo', 'secret': 'bar'}}
>>> s = get_session(config)
>>> s.access_key
'foo'
From the session object, you can access all of the functionality of the
``internetarchive`` lib:
>>> item = s.get_item('nasa')
>>> item.download()
nasa: ddddddd - success
>>> s.get_tasks(task_ids=31643513)[0].server
'ia311234'
Ú)rÚArchiveSession)rÚ config_fileÚdebugÚhttp_adapter_kwargss ú\/mnt/c/fieldcraft/witness-fracture/.venv/lib/python3.12/site-packages/internetarchive/api.pyÚ get_sessionr)s"€ôL × !Ñ ! &¨+Ò*;¸¸UÐDWÓ XÐXócóH—|st||||«}|j||¬«S)ayGet an :class:`Item` object.
:param identifier: The globally unique Archive.org item identifier.
:param config: A dictionary used to configure your session.
:param config_file: A path to a config file used to configure your session.
:param archive_session: An :class:`ArchiveSession` object can be provided
via the ``archive_session`` parameter.
:param debug: To be passed on to get_session().
:param http_adapter_kwargs: Keyword arguments that
:py:class:`requests.adapters.HTTPAdapter` takes.
:param request_kwargs: Keyword arguments that
:py:class:`requests.Request` takes.
:returns: The Item that fits the criteria.
Usage:
>>> from internetarchive import get_item
>>> item = get_item('nasa')
>>> item.item_size
121084
)Úrequest_kwargs)rÚget_item)Ú
identifierrrÚarchive_sessionrrrs rrrRs/€ñH Ü% f¨k¸5ÐBUÓVˆØ × #Ñ # J¸~Ð #Ó NÐNrc óF—t|fi|¤Ž}|j|||||«S)abGet :class:`File` objects from an item.
:param identifier: The globally unique Archive.org identifier for a given item.
:param files: Only return files matching the given filenames.
:param formats: Only return files matching the given formats.
:param glob_pattern: Only return files matching the given glob pattern.
:param exclude_pattern: Exclude files matching the given glob pattern.
:param on_the_fly: Include on-the-fly files (i.e. derivative EPUB,
MOBI, DAISY files).
:param \*\*get_item_kwargs: Arguments that ``get_item()`` takes.
:returns: Files from an item.
Usage:
>>> from internetarchive import get_files
>>> fnames = [f.name for f in get_files('nasa', glob_pattern='*xml')]
>>> print(fnames)
['nasa_reviews.xml', 'nasa_meta.xml', 'nasa_files.xml']
)rÚ get_files)rr ÚformatsÚ glob_patternÚexclude_patternÚ
on_the_flyÚget_item_kwargsr s rr r {s-€ôD �JÑ 2 /Ñ 2€DØ ˆ4�>‰>˜% ¨,¸ÈÓ TÐTrc
óR—t|fi|
¤Ž} | j||||||||| d¬«
S)aModify the metadata of an existing item on Archive.org.
:param identifier: The globally unique Archive.org identifier for a given item.
:param metadata: Metadata used to update the item.
:param target: The metadata target to update. Defaults to `metadata`.
:param append: set to True to append metadata values to current values
rather than replacing. Defaults to ``False``.
:param append_list: Append values to an existing multi-value
metadata field. No duplicate values will be added.
:param priority: Set task priority.
:param access_key: IA-S3 access_key to use when making the given request.
:param secret_key: IA-S3 secret_key to use when making the given request.
:param debug: set to True to return a :class:`requests.Request <Request>`
object instead of sending request. Defaults to ``False``.
:param \*\*get_item_kwargs: Arguments that ``get_item`` takes.
:returns: A Request if debug else a Response.
F) ÚtargetÚappendÚ append_listÚpriorityÚ
access_keyÚ
secret_keyrrÚrefresh)rÚmodify_metadata) rÚmetadatar'r(r)r*r+r,rrr%r s rr.r.¡sG€ôP �JÑ 2 /Ñ 2€DØ ˆ4× Ñ ØØØØØØØØØ%Øô ð rc ó\—t|fi|¤Ž}|j||||||||| |
| | |
||¬«S)aÆUpload files to an item. The item will be created if it does not exist.
:param identifier: The globally unique Archive.org identifier for a given item.
:param files: The filepaths or file-like objects to upload. This value can be an
iterable or a single file-like object or string.
:param metadata: Metadata used to create a new item. If the item already
exists, the metadata will not be updated -- use ``modify_metadata``.
:param headers: Add additional HTTP headers to the request.
:param access_key: IA-S3 access_key to use when making the given request.
:param secret_key: IA-S3 secret_key to use when making the given request.
:param queue_derive: Set to False to prevent an item from being derived
after upload.
:param verbose: Display upload progress.
:param verify: Verify local MD5 checksum matches the MD5 checksum of the
file received by IAS3.
:param checksum: Skip uploading files based on checksum.
:param delete: Delete local file after the upload has been successfully
verified.
:param retries: Number of times to retry the given request if S3 returns a
503 SlowDown error.
:param retries_sleep: Amount of time to sleep between ``retries``.
:param debug: Set to True to print headers to stdout, and exit without
sending the upload request.
:param validate_identifier: Set to True to validate the identifier before
uploading the file.
:param \*\*kwargs: Optional arguments that ``get_item`` takes.
:returns: A list Requests if debug else a list of Responses.
)r/Úheadersr+r,Ú queue_deriveÚverboseÚverifyÚchecksumÚdeleteÚretriesÚ
retries_sleeprÚvalidate_identifierr)rÚupload)rr r/r1r+r,r2r3r4r5r6r7r8rr9rr%r s rr:r:ØsT€ô~ �JÑ 2 /Ñ 2€DØ ˆ4�;‰;Ø
ØØØØØ!ØØØØØØ#ØØ/Ø%ô ðrc ó¤—t|fi|¤Ž}|jdid|“d|“d|“d|“d|“d|“d|“d|“d | “d
|
“d | “d | “d
|
“d|“d|“d|“d|“Ž}|S)aÑDownload files from an item.
:param identifier: The globally unique Archive.org identifier for a given item.
:param files: Only return files matching the given file names.
:param formats: Only return files matching the given formats.
:param glob_pattern: Only return files matching the given glob pattern.
:param dry_run: Print URLs to files to stdout rather than downloading
them.
:param verbose: Turn on verbose output.
:param ignore_existing: Skip files that already exist locally.
:param checksum: Skip downloading file based on checksum.
:param checksum_archive: Skip downloading file based on checksum, and skip
checksum validation if it already succeeded
(will create and use _checksum_archive.txt).
:param destdir: The directory to download files to.
:param no_directory: Download files to current working
directory rather than creating an item directory.
:param retries: The number of times to retry on failed
requests.
:param item_index: The index of the item for displaying
progress in bulk downloads.
:param ignore_errors: Don't fail if a single file fails to
download, continue to download other files.
:param on_the_fly: Download on-the-fly files (i.e. derivative EPUB,
MOBI, DAISY files).
:param return_responses: Rather than downloading files to disk, return
a list of response objects.
:param \*\*kwargs: Optional arguments that ``get_item`` takes.
:returns: A list Requests if debug else a list of Responses.
r r!r"Údry_runr3Úignore_existingr5Úchecksum_archiveÚdestdirÚ no_directoryr7Ú
item_indexÚ
ignore_errorsr$Úreturn_responsesÚno_change_timestampÚtimeout©)rÚdownload)rr r!r"r<r3r=r5r>r?r@r7rArBr$rCrDrEr%r Úrs rrGrG+sÑ€ôH �JÑ 2 /Ñ 2€D؈�
‰
ò Ùð áð ñ"ð ñð  ñ
ð  ñ (ð
 ñð ñ*ð ñð ñ"ð ñð ñð ñ$ð ñð ñ*ð ñ 0ð! ñ"ð# €Að&
€Hrc  ó„—t||||fi| ¤Ž}
g} |
D])} | j|||||¬«}
| j|
«Œ+| S)a¼Delete files from an item. Note: Some system files, such as <itemname>_meta.xml,
cannot be deleted.
:param identifier: The globally unique Archive.org identifier for a given item.
:param files: Only return files matching the given filenames.
:param formats: Only return files matching the given formats.
:param glob_pattern: Only return files matching the given glob pattern.
:param cascade_delete: Delete all files associated with the specified file,
including upstream derivatives and the original.
:param access_key: IA-S3 access_key to use when making the given request.
:param secret_key: IA-S3 secret_key to use when making the given request.
:param verbose: Print actions to stdout.
:param debug: Set to True to print headers to stdout and exit exit without
sending the delete request.
:returns: A list Requests if debug else a list of Responses
)Úcascade_deleter+r,r3r)r r6r()rr r!r"rJr+r,r3rÚkwargsÚ_filesÚ responsesÚfrHs rr6r6†sh€ôJ�z 5¨'°<Ñ
JÀ6Ñ
J€Fà€IØ
òˆØ
�H‰HØ)Ø!Ø!ØØð
ó
ˆð ×јÕðð ÐrcóJ—|st||d|«}|j|||¬«S)a/Get tasks from the Archive.org catalog.
:param identifier: The Archive.org identifier for which to retrieve tasks for.
:param params: The URL parameters to send with each request sent to the
Archive.org catalog API.
:returns: A set of :class:`CatalogTask` objects.
F)rÚparamsr)rÚ get_tasks)rrPrrrrrs rrQrQºs7€ñ$ Ü% f¨k¸5ÐBUÓVˆØ × $Ñ $Ø f¸^ð %ó ðrc
óT—|st||d| «}|j|||||||
| ¬«S)agSearch for items on Archive.org.
:param query: The Archive.org search query to yield results for. Refer to
https://archive.org/advancedsearch.php#raw for help formatting your
query.
:param fields: The metadata fields to return in the search results.
:param params: The URL parameters to send with each request sent to the
Archive.org Advancedsearch Api.
:param full_text_search: Beta support for querying the archive.org
Full Text Search API [default: False].
:param dsl_fts: Beta support for querying the archive.org Full Text
Search API in dsl (i.e. do not prepend ``!L `` to the
``full_text_search`` query [default: False].
:param secure: Configuration options for session.
:param config_file: A path to a config file used to configure your session.
:param http_adapter_kwargs: Keyword arguments that
:py:class:`requests.adapters.HTTPAdapter` takes.
:param request_kwargs: Keyword arguments that
:py:class:`requests.Request` takes.
:param max_retries: The number of times to retry a failed request.
This can also be an `urllib3.Retry` object.
If you need more control (e.g. `status_forcelist`), use a
`ArchiveSession` object, and mount your own adapter after the
session object has been initialized. For example::
>>> s = get_session()
>>> s.mount_http_adapter()
>>> search_results = s.search_items('nasa')
See :meth:`ArchiveSession.mount_http_adapter`
for more details.
:returns: A :class:`Search` object, yielding search results.
F)ÚfieldsÚsortsrPÚfull_text_searchÚdsl_ftsrÚ max_retries)rÚ search_items) ÚqueryrSrTrPrUrVrrrrrrWs rrXrXÓsI€ñr Ü% f¨k¸5ÐBUÓVˆØ × 'Ñ 'Ø
ØØØØ)ØØ%Øð (ó ð rcó”—tj|xs td«|xs td«|«}tj||«}|S)a]Configure internetarchive with your Archive.org credentials.
:param username: The email address associated with your Archive.org account.
:param password: Your Archive.org password.
:returns: The config file path.
Usage:
>>> from internetarchive import configure
>>> configure('user@example.com', 'password')
zEmail address: z
Password: )Ú
config_moduleÚget_auth_configÚinputrÚwrite_config_file)ÚusernameÚpasswordrÚhostÚ auth_configÚconfig_file_paths rÚ configurerdsM€ô$ ×/Ñ/ØÒ,”EÐ+Ó,ØÒ)”G˜LÓ)Ø ó€Kô
%×6Ñ6°{ÀKÓPÐØ Ðrcó>—t||«}|jdd«S)zøReturns an Archive.org username given an IA-S3 key pair.
:param access_key: IA-S3 access_key to use when making the given request.
:param secret_key: IA-S3 secret_key to use when making the given request.
:returns: The username.
r_r)Ú
get_user_infoÚget)r+r,Újs rÚ get_usernameri5s!€ô �j *Ó-€AØ �5‰5�˜RÓ Ð rcó—d}ddi}tj||tj||«d¬«}|j «|j «}|jd«rt
|jd««‚|S)a
Returns details about an Archive.org user given an IA-S3 key pair.
:param access_key: IA-S3 access_key to use when making the given request.