adsfolio.api.libraries

Libraries API wrapper for ADS.

Provides access to personal library management: - Create, read, update, delete libraries - Add/remove documents - Permissions management - Set operations (union, intersection, difference)

class adsfolio.api.libraries.LibrariesAPI(client)[source]

Bases: object

Libraries API for managing personal ADS libraries.

Examples

>>> api = LibrariesAPI(client)
>>> libs = api.list_libraries()
>>> lib = api.get_library(libs[0].id)
>>> print(lib.documents)
Parameters:

client (BaseClient)

add_documents(library_id, bibcodes)[source]

Add documents to a library.

Parameters:

  • library_id (str) – Library identifier.

  • bibcodes (list[str]) – Bibcodes to add.

Returns:

Response with number added.

Return type:

dict

create_library(name, description='My ADS library', public=False, bibcodes=None)[source]

Create a new library.

Parameters:

  • name (str) – Library name (must be unique for user).

  • description (str, optional) – Library description.

  • public (bool, optional) – Make library publicly accessible.

  • bibcodes (list[str], optional) – Initial bibcodes to add.

Returns:

Created library metadata.

Return type:

Library

delete_library(library_id)[source]

Delete a library.

Parameters:

library_id (str) – Library identifier.

Returns:

True if successful.

Return type:

bool

difference(primary_id, secondary_ids, name=None)[source]

Create difference of libraries (primary - secondary).

Parameters:
Return type:

adsfolio.api.libraries.Library

empty(library_id)[source]

Empty a library of all its contents.

Parameters:

library_id (str)

Return type:

adsfolio.api.libraries.Library

get_library(library_id, raw=False, start=0, rows=2000)[source]

Get a specific library with its documents.

Parameters:

  • library_id (str) – Unique library identifier.

  • raw (bool, optional) – If True, return exact bibcodes even if not in ADS.

  • start (int, optional) – Starting index for document pagination.

  • rows (int, optional) – Number of documents to return.

Returns:

Library with full document list.

Return type:

Library

intersection(primary_id, secondary_ids, name=None)[source]

Create intersection of libraries.

Parameters:
Return type:

adsfolio.api.libraries.Library

iter_documents(library_id, *, raw=False, rows=2000)[source]

Lazily iterate over every document in a library.

Parameters:

  • library_id (str) – Unique library identifier.

  • raw (bool, optional) – If True, return exact bibcodes even if not in ADS.

  • rows (int, optional) – Number of documents to request per page, up to 2,000.

Returns:

Bibcodes returned across all pages.

Return type:

iterator of str

Raises:

  • ValueError – If rows is not positive or exceeds 2,000.

  • ADSError – If the API repeats a non-empty page.

iter_libraries(*, rows=100, sort='date_created', order='asc')[source]

Lazily iterate over all libraries for the authenticated user.

Parameters:

  • rows (int, optional) – Number of libraries to request per page.

  • sort (str, optional) – Sort field: “date_created” or “date_last_modified”.

  • order (str, optional) – Sort order: “asc” or “desc”.

Returns:

Libraries returned across all pages.

Return type:

iterator of Library

Raises:

  • ValueError – If rows is not positive.

  • ADSError – If the API repeats a non-empty page.

list_libraries(start=0, rows=100, sort='date_created', order='asc')[source]

List all libraries for the authenticated user.

Parameters:

  • start (int, optional) – Starting index for pagination.

  • rows (int, optional) – Number of libraries to return.

  • sort (str, optional) – Sort field: “date_created” or “date_last_modified”.

  • order (str, optional) – Sort order: “asc” or “desc”.

Returns:

List of library metadata.

Return type:

list[Library]

operation(primary_id, action, secondary_ids=None, name=None, description=None, public=False)[source]

Perform set operations on libraries.

Parameters:

  • primary_id (str) – Primary library identifier.

  • action (str) – Operation: “union”, “intersection”, “difference”, “copy”, “empty”.

  • secondary_ids (list[str], optional) – Secondary library IDs (not needed for “empty”).

  • name (str, optional) – Name for new library (for union/intersection/difference).

  • description (str, optional) – Description for new library.

  • public (bool, optional) – Make new library public.

Returns:

Resulting library.

Return type:

Library

remove_documents(library_id, bibcodes)[source]

Remove documents from a library.

Parameters:

  • library_id (str) – Library identifier.

  • bibcodes (list[str]) – Bibcodes to remove.

Returns:

Response with number removed.

Return type:

dict

union(primary_id, secondary_ids, name=None)[source]

Create union of libraries.

Parameters:
Return type:

adsfolio.api.libraries.Library

update_library(library_id, name=None, description=None, public=None)[source]

Update library metadata.

Parameters:

  • library_id (str) – Library identifier.

  • name (str, optional) – New library name.

  • description (str, optional) – New description.

  • public (bool, optional) – New public status.

Returns:

Update response.

Return type:

dict

class adsfolio.api.libraries.Library(id, name, description='', num_documents=0, public=False, permission='', owner='', date_created=None, date_last_modified=None, documents=<factory>)[source]

Bases: object

Container for library metadata and documents.

Parameters:

  • id (str)

  • name (str)

  • description (str)

  • num_documents (int)

  • public (bool)

  • permission (str)

  • owner (str)

  • date_created (str | None)

  • date_last_modified (str | None)

  • documents (list[str])

date_created: str | None = None

ISO date when library was created.

date_last_modified: str | None = None

ISO date when library was last modified.

description: str = ''

Library description.

documents: list[str]

List of bibcodes in the library.

classmethod from_response(data)[source]

Create Library from API response.

Parameters:

data (dict)

Return type:

adsfolio.api.libraries.Library

id: str

Unique library identifier.

name: str

Library name.

num_documents: int = 0

Number of documents in the library.

owner: str = ''

Library owner identifier.

permission: str = ''

‘owner’, ‘admin’, ‘write’, ‘read’.

Type:

User’s permission level

public: bool = False

Whether the library is publicly accessible.