1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
.. _configuration:
Configuration
=============
Certain functionality of the internetarchive Python library requires your archive.org credentials.
Your `IA-S3 keys <https://archive.org/account/s3.php>`_ are required for uploading, searching, and modifying metadata, and your archive.org logged-in cookies are required for downloading access-restricted content and viewing your task history.
Your keys can be saved to a config file or set as environment variables.
Config File
-----------
To automatically create a config file with your archive.org credentials, you can use the ``ia`` command-line tool:
.. code-block:: console
$ ia configure
Enter your archive.org credentials below to configure 'ia'.
Email address: user@example.com
Password:
Config saved to: /home/user/.config/ia.ini
Your config file will be saved to ``$HOME/.config/ia.ini``, or ``$HOME/.ia`` if you do not have a ``.config`` directory in ``$HOME``.
Alternatively, you can specify your own path to save the config to via ``ia --config-file '~/.ia-custom-config' configure``.
If you have a netrc file with your archive.org credentials in it, you can simply run ``ia configure --netrc``.
``ia configure`` can be rerun at any time to update your credentials.
Custom configuration options manually added to the config file will be preserved when using ``ia configure``.
*Note: Python's netrc library does not currently support passphrases, or passwords with spaces in them, and therefore are not currently supported here.*
Config File Format
~~~~~~~~~~~~~~~~~~
Below is an example of a config file with the required sections and keys, as well as optional keys for advanced configuration. You should generally only configure with ``ia configure``, but you can manually edit the config file if needed.
.. code-block:: ini
[s3]
access = <IA-S3 Access Key>
secret = <IA-S3 Secret Key>
[cookies]
logged-in-user = <logged-in-user Cookie>
logged-in-sig = <logged-in-sig Cookie>
[general]
screenname = <Archive.org Screenname>
custom-var = foo
[custom]
foo = bar
The config above would generate the following configuration dictionary when loaded via the ``get_session`` function:
.. code-block:: python
>>> from internetarchive import get_session
>>> s = get_session(config_file='/tmp/ia.ini')
>>> print(s.config)
{'s3': {
'access': '<IA-S3 Access Key>',
'secret': '<IA-S3 Secret Key>'
},
'cookies': {
'logged-in-user': '<logged-in-user Cookie>',
'logged-in-sig': '<logged-in-sig Cookie>'},
'general': {
'screenname': '<Archive.org Screenname>',
'custom-var': 'foo'
},
'custom': {
'foo': 'bar'
}
}
Environment Variables
---------------------
Alternatively, you can set the following environment variables with your S3 credentials:
- ``IA_ACCESS_KEY_ID``: Your IA-S3 access key
- ``IA_SECRET_ACCESS_KEY``: Your IA-S3 secret key
*Note: Both environment variables must be set together. If only one is set, a* :class:`ValueError` *will be raised. If both are set, they will take precedence over the config file.*
|
