ebiblio-client 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ebiblio/__init__.py +13 -0
- ebiblio/cli.py +197 -0
- ebiblio/client.py +162 -0
- ebiblio/models.py +56 -0
- ebiblio/parser.py +301 -0
- ebiblio_client-0.1.0.dist-info/METADATA +784 -0
- ebiblio_client-0.1.0.dist-info/RECORD +11 -0
- ebiblio_client-0.1.0.dist-info/WHEEL +5 -0
- ebiblio_client-0.1.0.dist-info/entry_points.txt +2 -0
- ebiblio_client-0.1.0.dist-info/licenses/LICENSE +674 -0
- ebiblio_client-0.1.0.dist-info/top_level.txt +1 -0
ebiblio/__init__.py
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""Cliente de búsqueda para catálogos web basados en eBiblio."""
|
|
2
|
+
|
|
3
|
+
from .client import EbiblioClient, EbiblioError
|
|
4
|
+
from .models import Contributor, Medium, SearchResult, SearchResults
|
|
5
|
+
|
|
6
|
+
__all__ = [
|
|
7
|
+
"EbiblioClient",
|
|
8
|
+
"EbiblioError",
|
|
9
|
+
"Contributor",
|
|
10
|
+
"Medium",
|
|
11
|
+
"SearchResult",
|
|
12
|
+
"SearchResults",
|
|
13
|
+
]
|
ebiblio/cli.py
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
"""Interfaz de línea de comandos para ebiblio-client."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import sys
|
|
8
|
+
from typing import Sequence
|
|
9
|
+
|
|
10
|
+
from .client import EbiblioClient, EbiblioError
|
|
11
|
+
from .models import SearchResult
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _build_parser() -> argparse.ArgumentParser:
|
|
15
|
+
parser = argparse.ArgumentParser(
|
|
16
|
+
prog="ebiblio",
|
|
17
|
+
description=(
|
|
18
|
+
"Busca libros, películas y otros recursos "
|
|
19
|
+
"en un catálogo eBiblio."
|
|
20
|
+
),
|
|
21
|
+
)
|
|
22
|
+
parser.add_argument(
|
|
23
|
+
"url",
|
|
24
|
+
help="URL del catálogo (p. ej. https://madrid.ebiblio.es/)",
|
|
25
|
+
)
|
|
26
|
+
parser.add_argument(
|
|
27
|
+
"keywords",
|
|
28
|
+
nargs="?",
|
|
29
|
+
default="",
|
|
30
|
+
help="Palabras clave",
|
|
31
|
+
)
|
|
32
|
+
parser.add_argument(
|
|
33
|
+
"--page", type=int, default=1, help="Página que se consultará"
|
|
34
|
+
)
|
|
35
|
+
parser.add_argument(
|
|
36
|
+
"--all",
|
|
37
|
+
dest="all_pages",
|
|
38
|
+
action="store_true",
|
|
39
|
+
help="Recorrer todas las páginas",
|
|
40
|
+
)
|
|
41
|
+
parser.add_argument(
|
|
42
|
+
"--max-pages",
|
|
43
|
+
type=int,
|
|
44
|
+
default=100,
|
|
45
|
+
help="Límite de páginas para --all",
|
|
46
|
+
)
|
|
47
|
+
parser.add_argument(
|
|
48
|
+
"--timeout",
|
|
49
|
+
type=float,
|
|
50
|
+
default=20.0,
|
|
51
|
+
help="Tiempo máximo de espera en segundos",
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
parser.add_argument("--isbn")
|
|
55
|
+
parser.add_argument("--author")
|
|
56
|
+
parser.add_argument("--narrator")
|
|
57
|
+
parser.add_argument("--director")
|
|
58
|
+
parser.add_argument("--actor")
|
|
59
|
+
parser.add_argument("--publisher")
|
|
60
|
+
parser.add_argument("--collection-title")
|
|
61
|
+
parser.add_argument("--issued-on-range")
|
|
62
|
+
parser.add_argument("--language")
|
|
63
|
+
parser.add_argument("--audience")
|
|
64
|
+
parser.add_argument("--category")
|
|
65
|
+
parser.add_argument("--category-standard")
|
|
66
|
+
parser.add_argument("--nature")
|
|
67
|
+
parser.add_argument("--medium")
|
|
68
|
+
parser.add_argument("--sort-by")
|
|
69
|
+
parser.add_argument(
|
|
70
|
+
"--available",
|
|
71
|
+
action="store_true",
|
|
72
|
+
help="Limitar a títulos disponibles",
|
|
73
|
+
)
|
|
74
|
+
parser.add_argument(
|
|
75
|
+
"--json", action="store_true", help="Imprimir resultados como JSON"
|
|
76
|
+
)
|
|
77
|
+
return parser
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _filters_from_args(args: argparse.Namespace) -> dict[str, object]:
|
|
81
|
+
filters = {
|
|
82
|
+
"isbn": args.isbn,
|
|
83
|
+
"author": args.author,
|
|
84
|
+
"narrator": args.narrator,
|
|
85
|
+
"director": args.director,
|
|
86
|
+
"actor": args.actor,
|
|
87
|
+
"publisher": args.publisher,
|
|
88
|
+
"collection_title": args.collection_title,
|
|
89
|
+
"issued_on_range": args.issued_on_range,
|
|
90
|
+
"language": args.language,
|
|
91
|
+
"audience": args.audience,
|
|
92
|
+
"category": args.category,
|
|
93
|
+
"category_standard": args.category_standard,
|
|
94
|
+
"nature": args.nature,
|
|
95
|
+
"medium": args.medium,
|
|
96
|
+
"sort_by": args.sort_by,
|
|
97
|
+
}
|
|
98
|
+
selected = {
|
|
99
|
+
name: value
|
|
100
|
+
for name, value in filters.items()
|
|
101
|
+
if value is not None
|
|
102
|
+
}
|
|
103
|
+
if args.available:
|
|
104
|
+
selected["availability"] = True
|
|
105
|
+
return selected
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _print_result(item: SearchResult, index: int) -> None:
|
|
109
|
+
kind = item.resource_type or "Recurso"
|
|
110
|
+
print(f"{index}. {item.title} [{kind}]")
|
|
111
|
+
print(f" {item.url}")
|
|
112
|
+
for contributor in item.contributors:
|
|
113
|
+
print(
|
|
114
|
+
f" {contributor.role.capitalize()}: "
|
|
115
|
+
f"{', '.join(contributor.names)}"
|
|
116
|
+
)
|
|
117
|
+
if item.description:
|
|
118
|
+
print(f" {item.description}")
|
|
119
|
+
for medium in item.media:
|
|
120
|
+
details = [medium.format or "Medio"]
|
|
121
|
+
if medium.quality:
|
|
122
|
+
details.append(medium.quality)
|
|
123
|
+
if medium.availability:
|
|
124
|
+
details.append(medium.availability)
|
|
125
|
+
print(f" Medio: {' — '.join(details)}")
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
129
|
+
"""Punto de entrada del comando `ebiblio`."""
|
|
130
|
+
args = _build_parser().parse_args(argv)
|
|
131
|
+
filters = _filters_from_args(args)
|
|
132
|
+
try:
|
|
133
|
+
client = EbiblioClient(args.url, timeout=args.timeout)
|
|
134
|
+
if args.all_pages:
|
|
135
|
+
items = client.search_all(
|
|
136
|
+
args.keywords,
|
|
137
|
+
max_pages=args.max_pages,
|
|
138
|
+
**filters,
|
|
139
|
+
)
|
|
140
|
+
page_result = None
|
|
141
|
+
else:
|
|
142
|
+
page_result = client.search(
|
|
143
|
+
args.keywords,
|
|
144
|
+
page=args.page,
|
|
145
|
+
**filters,
|
|
146
|
+
)
|
|
147
|
+
items = page_result.items
|
|
148
|
+
except (EbiblioError, TypeError, ValueError) as exc:
|
|
149
|
+
print(f"ebiblio: {exc}", file=sys.stderr)
|
|
150
|
+
return 2
|
|
151
|
+
|
|
152
|
+
if args.json:
|
|
153
|
+
payload: dict[str, object] = {
|
|
154
|
+
"items": [_result_to_dict(item) for item in items]
|
|
155
|
+
}
|
|
156
|
+
if page_result is not None:
|
|
157
|
+
payload.update(
|
|
158
|
+
current_page=page_result.current_page,
|
|
159
|
+
page_numbers=page_result.page_numbers,
|
|
160
|
+
next_page_url=page_result.next_page_url,
|
|
161
|
+
)
|
|
162
|
+
else:
|
|
163
|
+
payload["all_pages"] = True
|
|
164
|
+
print(json.dumps(payload, ensure_ascii=False, indent=2))
|
|
165
|
+
return 0
|
|
166
|
+
|
|
167
|
+
if not items:
|
|
168
|
+
print("No se encontraron recursos.")
|
|
169
|
+
else:
|
|
170
|
+
for index, item in enumerate(items, start=1):
|
|
171
|
+
_print_result(item, index)
|
|
172
|
+
if page_result and page_result.next_page_url:
|
|
173
|
+
print(f"Página siguiente: {page_result.next_page_url}")
|
|
174
|
+
if args.all_pages:
|
|
175
|
+
print(f"Total de recursos recuperados: {len(items)}")
|
|
176
|
+
return 0
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def _result_to_dict(item: SearchResult) -> dict[str, object]:
|
|
180
|
+
"""Serializa el NamedTuple a un objeto JSON de estructura legible."""
|
|
181
|
+
return {
|
|
182
|
+
"title": item.title,
|
|
183
|
+
"url": item.url,
|
|
184
|
+
"resource_type": item.resource_type,
|
|
185
|
+
"resource_id": item.resource_id,
|
|
186
|
+
"cover_url": item.cover_url,
|
|
187
|
+
"description": item.description,
|
|
188
|
+
"contributors": {
|
|
189
|
+
contributor.role: contributor.names
|
|
190
|
+
for contributor in item.contributors
|
|
191
|
+
},
|
|
192
|
+
"media": [medium._asdict() for medium in item.media],
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
if __name__ == "__main__":
|
|
197
|
+
raise SystemExit(main())
|
ebiblio/client.py
ADDED
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
"""Cliente HTTP de solo lectura para búsquedas en catálogos eBiblio."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from http.cookiejar import CookieJar
|
|
6
|
+
from typing import Any
|
|
7
|
+
from urllib.error import HTTPError, URLError
|
|
8
|
+
from urllib.parse import parse_qs, urlencode, urljoin, urlsplit, urlunsplit
|
|
9
|
+
from urllib.request import HTTPCookieProcessor, Request, build_opener
|
|
10
|
+
|
|
11
|
+
from .models import SearchResult, SearchResults
|
|
12
|
+
from .parser import parse_search_results
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class EbiblioError(Exception):
|
|
16
|
+
"""Error de red o de respuesta del catálogo."""
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class EbiblioClient:
|
|
20
|
+
"""Busca recursos en un sitio compatible con el catálogo eBiblio.
|
|
21
|
+
|
|
22
|
+
Ejemplo::
|
|
23
|
+
|
|
24
|
+
client = EbiblioClient("https://madrid.ebiblio.es/")
|
|
25
|
+
results = client.search("Mabuse", language="spa", nature="ebook")
|
|
26
|
+
for item in results.items:
|
|
27
|
+
print(item.title, item.authors, item.url)
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
_search_fields = {
|
|
31
|
+
"isbn",
|
|
32
|
+
"author",
|
|
33
|
+
"narrator",
|
|
34
|
+
"director",
|
|
35
|
+
"actor",
|
|
36
|
+
"publisher",
|
|
37
|
+
"collection_title",
|
|
38
|
+
"issued_on_range",
|
|
39
|
+
"language",
|
|
40
|
+
"audience",
|
|
41
|
+
"category",
|
|
42
|
+
"nature",
|
|
43
|
+
"medium",
|
|
44
|
+
"availability",
|
|
45
|
+
"category_standard",
|
|
46
|
+
"sort_by",
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
def __init__(
|
|
50
|
+
self,
|
|
51
|
+
url: str,
|
|
52
|
+
*,
|
|
53
|
+
timeout: float = 20.0,
|
|
54
|
+
user_agent: str = "ebiblio-client/0.1 (+https://www.python.org/)",
|
|
55
|
+
) -> None:
|
|
56
|
+
parsed = urlsplit(url.strip())
|
|
57
|
+
if parsed.scheme not in {"http", "https"} or not parsed.netloc:
|
|
58
|
+
raise ValueError("La URL debe ser absoluta y usar http o https.")
|
|
59
|
+
if timeout <= 0:
|
|
60
|
+
raise ValueError("timeout debe ser mayor que cero.")
|
|
61
|
+
self.base_url = urlunsplit((parsed.scheme, parsed.netloc, "/", "", ""))
|
|
62
|
+
self.timeout = timeout
|
|
63
|
+
self.user_agent = user_agent
|
|
64
|
+
self._cookies = CookieJar()
|
|
65
|
+
self._opener = build_opener(HTTPCookieProcessor(self._cookies))
|
|
66
|
+
|
|
67
|
+
def _fetch(self, url: str) -> str:
|
|
68
|
+
request = Request(
|
|
69
|
+
url,
|
|
70
|
+
headers={
|
|
71
|
+
"User-Agent": self.user_agent,
|
|
72
|
+
"Accept": "text/html,application/xhtml+xml",
|
|
73
|
+
},
|
|
74
|
+
)
|
|
75
|
+
try:
|
|
76
|
+
with self._opener.open(request, timeout=self.timeout) as response:
|
|
77
|
+
charset = response.headers.get_content_charset() or "utf-8"
|
|
78
|
+
return response.read().decode(charset, errors="replace")
|
|
79
|
+
except (HTTPError, URLError, OSError) as exc:
|
|
80
|
+
raise EbiblioError(f"No se pudo consultar {url}: {exc}") from exc
|
|
81
|
+
|
|
82
|
+
def search(
|
|
83
|
+
self,
|
|
84
|
+
keywords: str = "",
|
|
85
|
+
*,
|
|
86
|
+
page: int = 1,
|
|
87
|
+
**filters: Any,
|
|
88
|
+
) -> SearchResults:
|
|
89
|
+
"""Ejecuta una búsqueda y devuelve los recursos de la página indicada.
|
|
90
|
+
|
|
91
|
+
Los filtros aceptan los nombres del formulario web (por ejemplo,
|
|
92
|
+
``author``, ``language``, ``category``, ``nature``, ``medium`` y
|
|
93
|
+
``availability``). También se admite ``q`` como alias de ``keywords``.
|
|
94
|
+
"""
|
|
95
|
+
if page < 1:
|
|
96
|
+
raise ValueError("page debe ser un entero positivo.")
|
|
97
|
+
if "q" in filters:
|
|
98
|
+
if keywords:
|
|
99
|
+
raise TypeError("Usa keywords o q, pero no ambos.")
|
|
100
|
+
keywords = filters.pop("q")
|
|
101
|
+
|
|
102
|
+
unknown = set(filters) - self._search_fields
|
|
103
|
+
if unknown:
|
|
104
|
+
fields = ", ".join(sorted(unknown))
|
|
105
|
+
raise TypeError(f"Filtros no reconocidos: {fields}")
|
|
106
|
+
|
|
107
|
+
params: dict[str, str] = {
|
|
108
|
+
"category_standard": "ebiblio",
|
|
109
|
+
"page": str(page),
|
|
110
|
+
}
|
|
111
|
+
if keywords:
|
|
112
|
+
params["keywords"] = str(keywords)
|
|
113
|
+
for name, value in filters.items():
|
|
114
|
+
if value is None or value is False:
|
|
115
|
+
continue
|
|
116
|
+
if name == "availability" and value is True:
|
|
117
|
+
params[name] = "available"
|
|
118
|
+
else:
|
|
119
|
+
params[name] = str(value)
|
|
120
|
+
|
|
121
|
+
search_url = urljoin(self.base_url, "/resources")
|
|
122
|
+
request_url = f"{search_url}?{urlencode(params)}"
|
|
123
|
+
html = self._fetch(request_url)
|
|
124
|
+
parsed = parse_search_results(html, self.base_url)
|
|
125
|
+
next_page_url = parsed.next_page_url
|
|
126
|
+
return SearchResults(
|
|
127
|
+
items=parsed.items,
|
|
128
|
+
current_page=(
|
|
129
|
+
parsed.current_page
|
|
130
|
+
if parsed.current_page > 1 or page == 1
|
|
131
|
+
else page
|
|
132
|
+
),
|
|
133
|
+
page_numbers=parsed.page_numbers,
|
|
134
|
+
next_page_url=next_page_url,
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
def search_all(
|
|
138
|
+
self,
|
|
139
|
+
keywords: str = "",
|
|
140
|
+
*,
|
|
141
|
+
max_pages: int = 100,
|
|
142
|
+
**filters: Any,
|
|
143
|
+
) -> tuple[SearchResult, ...]:
|
|
144
|
+
"""Recorre páginas siguientes hasta el final o ``max_pages``."""
|
|
145
|
+
if max_pages < 1:
|
|
146
|
+
raise ValueError("max_pages debe ser un entero positivo.")
|
|
147
|
+
results: list[SearchResult] = []
|
|
148
|
+
page = 1
|
|
149
|
+
while page <= max_pages:
|
|
150
|
+
current = self.search(keywords, page=page, **filters)
|
|
151
|
+
results.extend(current.items)
|
|
152
|
+
if not current.next_page_url:
|
|
153
|
+
break
|
|
154
|
+
next_page = parse_qs(
|
|
155
|
+
urlsplit(current.next_page_url).query
|
|
156
|
+
).get("page", [])
|
|
157
|
+
page = (
|
|
158
|
+
int(next_page[0])
|
|
159
|
+
if next_page and next_page[0].isdigit()
|
|
160
|
+
else page + 1
|
|
161
|
+
)
|
|
162
|
+
return tuple(results)
|
ebiblio/models.py
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"""Modelos inmutables de datos devueltos por el cliente."""
|
|
2
|
+
|
|
3
|
+
from typing import NamedTuple
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Medium(NamedTuple):
|
|
7
|
+
"""Una edición o medio disponible para un recurso del catálogo."""
|
|
8
|
+
|
|
9
|
+
format: str
|
|
10
|
+
quality: str | None = None
|
|
11
|
+
availability: str | None = None
|
|
12
|
+
availability_count: int | None = None
|
|
13
|
+
borrow_url: str | None = None
|
|
14
|
+
streaming: bool = False
|
|
15
|
+
accessible: bool = False
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class Contributor(NamedTuple):
|
|
19
|
+
"""Colaborador asociado a un recurso y sus nombres."""
|
|
20
|
+
|
|
21
|
+
role: str
|
|
22
|
+
names: tuple[str, ...]
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class SearchResult(NamedTuple):
|
|
26
|
+
"""Un libro, película u otro recurso del catálogo."""
|
|
27
|
+
|
|
28
|
+
title: str
|
|
29
|
+
url: str
|
|
30
|
+
resource_type: str | None = None
|
|
31
|
+
resource_id: str | None = None
|
|
32
|
+
cover_url: str | None = None
|
|
33
|
+
description: str | None = None
|
|
34
|
+
contributors: tuple[Contributor, ...] = ()
|
|
35
|
+
media: tuple[Medium, ...] = ()
|
|
36
|
+
|
|
37
|
+
@property
|
|
38
|
+
def authors(self) -> tuple[str, ...]:
|
|
39
|
+
"""Devuelve los colaboradores etiquetados como autor."""
|
|
40
|
+
return next(
|
|
41
|
+
(
|
|
42
|
+
contributor.names
|
|
43
|
+
for contributor in self.contributors
|
|
44
|
+
if contributor.role == "autor"
|
|
45
|
+
),
|
|
46
|
+
(),
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class SearchResults(NamedTuple):
|
|
51
|
+
"""Página de resultados e información para continuar la paginación."""
|
|
52
|
+
|
|
53
|
+
items: tuple[SearchResult, ...]
|
|
54
|
+
current_page: int = 1
|
|
55
|
+
page_numbers: tuple[int, ...] = ()
|
|
56
|
+
next_page_url: str | None = None
|