Skip to content

Commit b3ee200

Browse files
jjjakejjjake
committed
Doc refactor
1 parent ff646cd commit b3ee200

File tree

2 files changed

+271
-0
lines changed

2 files changed

+271
-0
lines changed

‎docs/source/configuration.rst‎

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

‎docs/source/modules.rst‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
.. _modules:
2+
3+
Module Documentation
4+
====================
5+
6+
This section contains complete reference documentation for all modules, classes, and methods in the ``internetarchive`` package. For a gentler introduction with examples, see :ref:`python-lib`.
7+
8+
Core Modules
9+
------------
10+
11+
These modules provide the main functionality for interacting with archive.org.
12+
13+
.. _api-module:
14+
15+
internetarchive.api module
16+
~~~~~~~~~~~~~~~~~~~~~~~~~~
17+
18+
The convenience module providing simple functions for common tasks.
19+
20+
.. automodule:: internetarchive.api
21+
:members:
22+
:undoc-members:
23+
:show-inheritance:
24+
:special-members: __init__
25+
:noindex:
26+
27+
.. _session-module:
28+
29+
internetarchive.session module
30+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31+
32+
The session management module for persisting configuration and connections.
33+
34+
.. automodule:: internetarchive.session
35+
:members:
36+
:undoc-members:
37+
:show-inheritance:
38+
:special-members: __init__
39+
:noindex:
40+
41+
.. _item-module:
42+
43+
internetarchive.item module
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
45+
46+
Modules for working with archive.org items and collections.
47+
48+
.. automodule:: internetarchive.item
49+
:members:
50+
:undoc-members:
51+
:show-inheritance:
52+
:special-members: __init__
53+
:noindex:
54+
55+
.. _account-module:
56+
57+
internetarchive.account module
58+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59+
60+
Module for managing an archive.org account (requires admin privileges).
61+
62+
.. automodule:: internetarchive.account
63+
:members:
64+
:undoc-members:
65+
:show-inheritance:
66+
:special-members: __init__
67+
:noindex:
68+
69+
.. _search-module:
70+
71+
internetarchive.search module
72+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
73+
74+
Modules for searching and retrieving items from archive.org.
75+
76+
.. automodule:: internetarchive.search
77+
:members:
78+
:undoc-members:
79+
:show-inheritance:
80+
:special-members: __init__
81+
:noindex:
82+
83+
File Operations
84+
---------------
85+
86+
Modules for working with files and specific file operations.
87+
88+
.. automodule:: internetarchive.files
89+
:members:
90+
:undoc-members:
91+
:show-inheritance:
92+
:special-members: __init__
93+
:noindex:
94+
95+
Request Handling
96+
----------------
97+
98+
Modules for making HTTP requests to archive.org services.
99+
100+
.. automodule:: internetarchive.iarequest
101+
:members:
102+
:undoc-members:
103+
:show-inheritance:
104+
:special-members: __init__
105+
:noindex:
106+
107+
Task and Catalog Management
108+
---------------------------
109+
110+
Modules for working with archive.org tasks and the catalog system.
111+
112+
.. automodule:: internetarchive.catalog
113+
:members:
114+
:undoc-members:
115+
:show-inheritance:
116+
:special-members: __init__
117+
:noindex:
118+
119+
Authentication and Configuration
120+
--------------------------------
121+
122+
Modules for authentication, configuration, and utility functions.
123+
124+
.. automodule:: internetarchive.auth
125+
:members:
126+
:undoc-members:
127+
:show-inheritance:
128+
:special-members: __init__
129+
:noindex:
130+
131+
.. automodule:: internetarchive.config
132+
:members:
133+
:undoc-members:
134+
:show-inheritance:
135+
:special-members: __init__
136+
:noindex:
137+
138+
Utility and Supporting Modules
139+
------------------------------
140+
141+
Internal utilities and supporting modules.
142+
143+
.. automodule:: internetarchive.utils
144+
:members:
145+
:undoc-members:
146+
:show-inheritance:
147+
:special-members: __init__
148+
:noindex:
149+
150+
.. automodule:: internetarchive.exceptions
151+
:members:
152+
:undoc-members:
153+
:show-inheritance:
154+
:noindex:
155+
156+
CLI Modules (Internal)
157+
----------------------
158+
159+
.. note::
160+
These modules are primarily used by the command-line interface and are considered
161+
internal to the package. For using the CLI, see :ref:`cli`.
162+
163+
.. automodule:: internetarchive.cli
164+
:members:
165+
:undoc-members:
166+
:show-inheritance:
167+
:special-members: __init__
168+
:noindex:
169+
170+
Complete Package Reference
171+
--------------------------
172+
173+
For a complete listing of all modules and classes:
174+
175+
.. automodule:: internetarchive
176+
:members:
177+
:undoc-members:
178+
:show-inheritance:
179+
:noindex:

0 commit comments

Comments
 (0)