API de Python

O SDK chama a API pública padrão de Rust por meio de uma extensão nativa. Ele inclui py.typed e assinaturas públicas verificadas. Comece pelo guia de início rápido.

Valores de projeto e nota

Entrada	Comportamento
Project(namespace, *, default_deck=None)	Valida o namespace estável explícito e configura o baralho padrão
project.add(key, note)	Incorpora atomicamente a nota, o modelo e a mídia com dados próprios; chaves de nota duplicadas causam falha
project.add_asset(media)	Inclui uma dependência explícita de HTML/CSS/script bruto
len(project)	Quantidade de notas adicionadas com sucesso
Note.basic(front, back)	Modelo Basic integrado; strings representam Text
Note.cloze(text)	Modelo Cloze integrado; strings representam Text e preservam a sintaxe Cloze
note.field(key, content)	Retorna uma nova nota com a atribuição do campo; a chave é validada na adição
note.deck(name) / .tag(tag) / .tags(tags)	Retorna uma nota configurada
note.note_type	O modelo imutável mantido pela nota

Strings comuns se tornam Text. Content.text(value) e Content.html(value) são construtores explícitos; Content.sequence(iterable) combina strings e conteúdo sem renderizar nem perder dependências de mídia. Um campo não aceita um nome de arquivo bruto como referência de mídia.

Modelos e templates

NoteType.builder(key) retorna um builder imutável. Seus métodos .name, .field, .template, .css, .cloze_field e .asset retornam builders atualizados. .build() valida a definição completa e retorna um NoteType imutável. model.note() cria uma nota que mantém esse modelo. NoteType.from_bundle(path, limits=MediaLimits()) carrega o mesmo modelo e seus recursos a partir do formato atual de pacote; o limite opcional é aplicado separadamente a cada recurso antes da leitura.

Field(key, name=None, required=False, sort=False) separa a chave estável do nome de exibição. Template(key, front, back, name=None, browser_front=None, browser_back=None, target_deck=None, generation=GenerationRule()) usa chaves de campo em todas as strings de origem. GenerationRule.all(keys) e .any(keys) configuram a geração de cartões. O padrão infere a condição de presença de campo do Anki. .cloze_field(key) no builder declara uma geração Cloze personalizada.

Mídia e oclusão

Entrada	Comportamento
Media.file(path, *, limits=MediaLimits())	Lê imediatamente um snapshot com dados próprios
Media.bytes(data, media_type, *, limits=MediaLimits())	Mantém bytes com um tipo MIME explícito
media.with_export_name(name)	Retorna um novo valor de nome de arquivo que compartilha o snapshot; referências anteriores preservam seus nomes
media.filename, media.media_type, len(media)	Metadados do snapshot somente para leitura
media.image() / .sound()	Conteúdo tipado que mantém o snapshot

MediaLimits(max_bytes=256 << 20) controla cada importação antes da criação do snapshot. Mídias grandes podem usar armazenamento temporário sob sua própria responsabilidade. Conflitos de nomes são verificados entre todos os recursos explícitos e incorporados automaticamente.

Note.image_occlusion(media) retorna um ImageOcclusionBuilder. Encadeie .mask(Mask.rect(key, x, y, width, height)), opcionalmente .mode(OcclusionMode.HIDE_ONE_GUESS_ONE) e, por fim, .build(). O modo padrão é HIDE_ALL_GUESS_ONE. A finalização decodifica a imagem e valida chaves estáveis de máscara e coordenadas finitas em pixels dentro da imagem. Na Note retornada, defina header, back_extra ou comments normalmente. Os campos gerados image e occlusion não podem ser atribuídos manualmente.

Operações e resultados

Entrada	Resultado
project.build(BuildOptions.to(path))	BuildOutput com um artefato persistente garantido
project.build(BuildOptions.temporary())	BuildOutput com um artefato temporário de vida útil controlada
options.update_from(path)	Retorna opções para atualizar a partir das evidências completas da base
project.compare(CompareOptions.against(path))	ComparisonReport concluído, incluindo uma decisão separada de política de publicação
options.update_policy(policy)	Aplica uma política de risco explícita a Update/Compare; inválida para Create
options.inspect_limits(limits)	Aplica limites finitos de forma independente à base e ao candidato

BuildOutput tem .artifact, .report e .snapshot(). BuildReport oferece .counts (BuildCounts com notes/cards/media), .diagnostics, .comparison e .snapshot(). Um relatório não informa o resultado da operação nem mantém um proprietário de arquivo. ComparisonReport oferece .findings, .policy, .allows_publication e .snapshot(). Snapshots são dicionários comuns serializáveis em JSON e não mantêm a propriedade de artefatos.

ApkgArtifact oferece .path, .persist_to(path) e .close(). Copiá-lo com copy.copy mantém outro proprietário; um gerenciador de contexto libera esse proprietário na saída. Uma saída temporária desaparece quando seu último proprietário é liberado. Caminhos persistentes permanecem após a liberação dos handles. Uma falha na persistência mantém o handle de origem utilizável.

UpdatePolicy() bloqueia resultados High e Critical. .fail_on(RiskLevel.MEDIUM) altera o limiar. .allow('RISK.NOTE_REMOVED') autoriza explicitamente toda a categoria registrada, preservando as evidências. Códigos desconhecidos causam falha imediata. InspectLimits expõe todos os limites finitos de bytes/contagens, incluindo max_identity_bytes; não é possível desativar inspeções obrigatórias.

Erros e concorrência

Falhas geram SchemaError, AddError, MediaError, ImageOcclusionError, TemplateBundleError, CompareError, PolicyError, BuildError ou PersistError. Cada um oferece kind, code, details, observações estruturadas em source_details e o texto da cadeia de causas em causes, além de preservar a exceção nativa como __cause__. Causas de E/S mantêm um OSError encadeado quando disponível. BuildError oferece .report e .snapshot(); CompareError oferece um .report parcial; os detalhes de PersistError incluem os fatos reais da publicação.

Operações nativas de Project liberam o GIL e rejeitam o uso simultâneo do mesmo objeto com BINDING.PROJECT_BUSY; projetos independentes podem executar concorrentemente. Após um fork do processo, recrie todos os valores e handles nativos. Handles herdados rejeitam operações com BINDING.FORKED_OBJECT, e sua liberação não remove arquivos pertencentes ao processo pai. Valores criados pelo processo filho funcionam e são liberados normalmente. Veja diagnósticos.

Contexto da adição

Adições que falham deixam o projeto inalterado. O contexto estruturado registra as chaves originais da nota/modelo e o alvo, com detalhes opcionais de conflito ou uso de mídia. Rust oferece note::{AddContext, AddTarget, AddDetail} por meio de AddError::context() / detail(); os SDKs oferecem AddError.details com contexto/detalhes tipados. Os campos de Node usam camelCase e são profundamente congelados; Python usa TypedDicts em snake_case. Tags preservam seu índice de inserção; localizações de campo preservam os índices originais da sequência (null/None para o campo, [] para sua raiz) e intervalos opcionais de bytes UTF-8. Erros de baralho padrão na geração não têm chaves de nota/modelo e continuam disponíveis na cadeia de causas.

Imagens tipadas exigem MIME image/* na adição; referências de som aceitam audio/* ou video/*. Outras categorias geram NOTE.MEDIA_USAGE_INVALID. Os construtores continuam sem possibilidade de falha; recursos explícitos e HTML bruto não são afetados. A verificação usa o MIME preservado na importação e não certifica a reprodução. A validação independente de MIME/extensão durante a geração continua valendo. Veja o documento de projeto para a tabela completa de alvos/detalhes.

Detalhes adicionais da API

A importação de mídia em lote e a publicação preparada estão incluídas no pacote público 0.3.1.

Prepare, revise e publique

from ankiforge import Project, Note, BuildOptions, BuildError
project = Project('review-once').add('one', Note.basic('Question', 'Answer'))
previous = project.build(BuildOptions.to('previous.apkg'))
previous.artifact.close()
prepared = project.prepare_publication(
    BuildOptions.to('next.apkg').update_from('previous.apkg')
)
try:
    report = prepared.report  # observations; does not own the candidate
    if report.comparison is None or report.comparison.allows_publication:
        output = prepared.publish()
        output.artifact.close()  # persistent next.apkg remains
except BuildError as error:
    print(error.snapshot()['result'])  # actual publication/durability facts
    raise
finally:
    prepared.close()  # idempotent; deletes an unused candidate

Uma tentativa de publicação consome o proprietário, inclusive quando há falha de política ou E/S. Chamadas posteriores geram PreparedPublicationStateError com o código BUILD.PREPARED_UNAVAILABLE e o motivo closed ou consumed; close não cancela uma publicação já em andamento. Caminhos relativos são fixados na chamada de preparação, e alterações no Project não modificam o APKG revisado. Relatórios continuam disponíveis após close sem manter arquivos. Para alterar opções ou tentar novamente, faça outra preparação. A duração não inclui o tempo de espera pela revisão. Erros tardios podem significar que a substituição foi bem-sucedida, mas a durabilidade não foi confirmada; consulte os fatos da publicação antes de decidir o que fazer. São necessários o protocolo 1 do binding nativo e o pacote de contratos 2.1.0; binários mais antigos com o mesmo número de versão são rejeitados.