Após clonar o projeto e entrar na pasta, digite:
# Crie uma virtualenv
python -m venv .venv
# Ative
source .venv/bin/activate
# Instale os pacotes
pip install -r requirements.txt
ClassicIdFile é a interface para ler os arquivos .id (saída do i2id)
das bases title, issue e artigo do site clássico. Ela complementa
ClassicWebsite, cujos métodos continuam funcionando como antes.
- Lê o arquivo linha a linha: a memória fica constante (~20 MB), independentemente do tamanho do arquivo.
- Para filtrar, lê só o PID e a data. O JSON completo só é montado para os itens usados.
- Filtra por data, PID e tipo de item.
- Em
artigo, junta os registros de cada documento e inclui os registrospque ficam em arquivos externos.
Pela ClassicWebsite (forma recomendada; aceita base ISIS ou .id):
cw = ClassicWebsite(bases_path, bases_work_path, ...)
journals = cw.get_journals_id_file() # base title
issues = cw.get_issues_id_file() # base issue
for docs in cw.get_documents_id_files(acron, issue_folder=..., issue_pid=...):
... # base(s) artigo do fascículoPara artigo, a ClassicWebsite já configura a busca dos registros p
externos em [bases_work_path, bases_path].
Direto, informando o tipo e o caminho do .id:
from scielo_classic_website.iid2json.id_file import ClassicIdFile
journals = ClassicIdFile("title", "/bases/title/title.id") # ou "journal"
issues = ClassicIdFile("issue", "/bases/issue/issue.id")
docs = ClassicIdFile(
"artigo", # ou "article"
"/bases-work/mioc/mioc.id",
p_records_base_paths=[bases_work_path, bases_path], # opcional
)Sem p_records_base_paths, os registros p externos não são incluídos.
items() retorna um IdFileItem por vez, somente os itens bons (os lotes
quebrados ficam em broken_batches()):
# title e issue: um registro por item
for item in issues.items(since="20240101"):
item.pid # 0074-027620240001
item.date # "YYYYMMDD"
item.data # o registro em JSON
# artigo: documentos
for item in docs.items(kind="document", since=last_run_date):
item.pid # S0074-02762024000100001
item.issue_pid # 0074-027620240001
item.date # v091 do registro "o"
item.records # todos os registros do documento (o, h, f, l, c, p, ...)
item.p_records # só os registros "p" (do arquivo principal ou externo)
# artigo: registros "i" (fascículo)
for item in docs.items(kind="issue"):
item.dataFiltros de items(), que podem ser combinados:
| Parâmetro | Uso |
|---|---|
since, until |
Datas YYYYMMDD ("20240315"), date ou datetime. since: data igual ou maior; until: data igual ou menor. |
pids |
Lista de PIDs. |
kind |
"document" ou "issue" em artigo; "journal" em title; "issue" em issue. |
date_field |
Campo de data: "update" (padrão), "creation", "publication" (só artigo) ou uma tag ("v091"). |
include_undated |
Com filtro de data, inclui itens sem data (padrão False). |
Campos de data por base:
| Base | update |
creation |
publication |
|---|---|---|---|
| title | v941 | v940 | — |
| issue | v091 | v093 | — |
| artigo | v091 | v093 | v065 |
A data de cada item vem do primeiro registro do item que tem o campo. Em
artigo, o v091 fica no registro o.
Outras formas de leitura:
docs.pids(**filtros) # só PIDs
docs.pids_and_dates(**filtros) # (pid, date)
docs.pids_and_records(**filtros) # (pid, records), mesmo formato de id2json3
docs.pids_dates_and_records(**filtros) # (pid, date, records)item = docs.get(pid) # uma busca: lê o arquivo até o fim
docs.build_index() # várias buscas: monta o índice uma vez
for pid in pids:
item = docs.get(pid) # acesso direto, menos de 1 ms por buscaSe um PID aparece mais de uma vez no arquivo, get() e o índice retornam a
última ocorrência. items() retorna todas. Lotes quebrados são ignorados por
items(), get() e o índice: um o solto depois do documento completo não
o substitui.
O mesmo de id2json3.pids_and_their_records: uma lista de registros, cada
um um dicionário tag -> lista de ocorrências, com os subcampos como chaves
e o conteúdo sem subcampo em "_":
[
{"v706": [{"_": "o"}], "v880": [{"_": "S0074-02762024000100001"}], "v091": [{"_": "20240115"}]},
{"v706": [{"_": "h"}], "v012": [{"_": "Título", "l": "pt"}, {"_": "Title", "l": "en"}]},
...
]- Os registros de um documento formam um lote que segue a ordem
o,h,f,l,p,c,r. Tipos podem faltar, mas a ordem não se inverte (onunca vem depois deh), e sóp,cerse repetem. Um novo lote começa quando a ordem se inverte, quando um tipo que não se repete aparece de novo ou quando o PID muda. - O registro
i(fascículo) não faz parte de nenhum documento. Ele é retornado como item próprio (kind="issue"), mesmo quando está no meio dos registros de um documento. - Registros sem v706 (por exemplo, só
v880=Sev936) são ignorados. - Registros
p: se o documento tempno arquivo principal, eles são usados e o arquivo externo não é consultado. Se não tem,recordsinclui ospde{base}/artigo/p/{pid[1:10]}/{pid[10:14]}/{pid[14:18]}/{pid[-5:]}.id, quando o arquivo existe. Se não existe, o documento fica semp. kind="document": lote que começa como, temhe PID de 23 caracteres. Qualquer outro lote ékind="broken".
Lotes quebrados não são documentos e não devem ser processados como
tais. Por isso items() (e pids(), pids_and_records(), get()...) não
os retorna: eles ficam separados, para auditoria. A biblioteca não os avalia
nem gera erro, e eles não são filtrados (os filtros de data, PID e kind são
de items()):
for batch in docs.broken_batches(): # todos os lotes; sem filtros
batch.pid
batch.record_types # ("h", "f", "l", "c", ...)
batch.mfn, batch.last_mfn, batch.offset
batch.recordsExemplos encontrados num arquivo real: um o solto (o documento completo
aparece mais adiante) e um lote h, f, l, c... sem o.
Para ler os itens bons e os lotes quebrados sem ler o arquivo duas vezes,
chame broken_batches() depois de uma leitura completa:
for item in docs.items(): # leitura completa: registra a posição
... # (offset) de cada lote quebrado
for batch in docs.broken_batches(): # lê só os lotes, a partir das posições
...- O custo é um inteiro por lote quebrado.
- Contam como leitura completa
items(),pids(),build_index(),get()sem índice etc., com qualquer filtro, desde que o consumidor não interrompa a leitura. - Se não houve leitura completa, ou se o arquivo mudou desde então (tamanho
ou data de modificação),
broken_batches()lê o arquivo inteiro.
Em todas as bases, quebras de linha dentro do conteúdo de um campo viram um
espaço simples. Só é campo novo uma linha !v<tag>! e só é registro novo
uma linha !ID <número>.
- Não use
list(docs.items()): isso carrega tudo na memória. Processe item a item. - Só acesse
item.recordsquando for usar os registros. Para decidir o que processar, usepid,dateekind. - Para ler só o que mudou, guarde a data da última execução e passe-a em
since. O arquivo é lido inteiro, mas só os itens no intervalo são convertidos. - A posição no arquivo não indica a data: o arquivo está em ordem de processamento, e o v091 de cada artigo pode ser anterior à data de processamento do fascículo. Não interrompa a leitura com base na data.
- O v091 de um artigo pode se manter quando o fascículo é reprocessado. Se
for preciso detectar reprocessamentos, compare por fascículo (por exemplo,
pelo v091 do registro
i) ou pelo conteúdo.
Comparação com id2json3.pids_and_their_records (usado pelos métodos
antigos de ClassicWebsite) em um .id real de artigos (153 MB, 214 mil
registros):
| Operação | id2json3 |
ClassicIdFile |
|---|---|---|
| Converter tudo para JSON | 6,9 s / 540 MB | 7,7 s / 24 MB |
| Filtro por data + JSON dos itens filtrados | 6,9 s / 540 MB | 3,1 s / 22 MB |
| Só PIDs e datas | 6,9 s / 540 MB | 3,1 s / 19 MB |
| Buscar um PID | 6,8 s / 540 MB | 3,0 s / 19 MB |
100 buscas (com build_index()) |
~680 s | 3,0 s (índice) + 0,08 s |
Lotes quebrados depois de items() |
— | 0,006 s (138 lotes) |
A memória do id2json3 cresce com o tamanho do arquivo (cerca de 1 GB para
um arquivo de 400 MB). A do ClassicIdFile fica constante.
ClassicWebsite (antigo) |
Nova interface |
|---|---|
get_journals_pids_and_records() |
cw.get_journals_id_file().pids_and_records() |
get_issues_pids_and_records() |
cw.get_issues_id_file().pids_and_records() |
get_document_records(source_paths) |
cw.get_documents_id_files(...) e .items(kind="document") |
get_issue_doc_records(...) |
items(), separando por item.kind e item.issue_pid |
get_p_records(pid) |
item.p_records |
Em relação ao id2json3, ClassicIdFile se comporta de forma diferente em
alguns casos:
- registros
irepetidos ou no meio de um documento não separam o documento; - registros sem v706 não são anexados ao documento seguinte;
- lotes sem registro
oouhsãokind="broken", não documentos; - campos com o byte
\x85não são cortados; - linhas vazias são ignoradas;
- arquivo inexistente gera
FileNotFoundError, em vez de retornar uma lista vazia.
record,tag,subfield,subfield_name,multi_val,composite,field_name,name,description
Issue,31,,,,,volume,volume,Volume
Issue,32,,,,,number,number,Number
Issue,43,,,,,_start_end_months, start end months, Start End Months
Issue,,,,,,start_month,start month,Start Month
Issue,,,,,,end_month,end month,End Month
Issue,131,,,,,supplement_volume,supplement volume,Supplement Volume
Issue,132,,,,,supplement_number,supplement number,Supplement Number
Issue,,,,,,is_ahead_of_print,is ahead of print,Is Ahead Of Print
Create a JSON version of tests/fixtures/models_builder/issue_record.csv (/path/output/issue.json)
python scielo_classic_website/cli/models_builder.py generate_json_data_dictionary tests/fixtures/models_builder/issue_record.csv /path/output/issue.jsonCreate the python modules /path/output/base_issue.py and /path/output/issue.py given a CSV file (issue_record.csv)
python scielo_classic_website/cli/models_builder.py generate_model tests/fixtures/models_builder/issue_record.csv Issue Issue /path/output/issue.py