imprintlab 0.1.4

Lib para pré-modelar certificados, crachás e templates visuais

Imprint — Documentação (Português / English)

Esta documentação contém versões em Português (PT-BR) e English (EN) do README e guias rápidos para a biblioteca Imprint.

---

Português (PT-BR)

Imprint

Imprint é uma biblioteca Python para criação e geração programática de templates visuais (certificados, crachás, convites e outros), com campos dinâmicos que podem ser preenchidos a partir de APIs, planilhas, bancos de dados ou qualquer fonte de dados.

⚡ Principais recursos

• Criação de templates personalizados com múltiplas páginas.
• Campos dinâmicos: texto, imagem e QR code (e mais tipos no futuro).
• Definição de posição, tamanho e dimensões para cada campo em uma página.
• Exportação para imagens PNG e suporte planejado para PDF e outros formatos.
• Integração fácil com APIs, Excel/CSV e bancos de dados.
• Arquitetura modular para facilitar adição de novos tipos de campos e motores de render (engines).

🚀 Instalação

Quando publicado no PyPI:

pip install imprintlab

Para instalar diretamente do repositório durante desenvolvimento:

pip install git+https://github.com/danieldevpy/imprint.git

📝 Exemplo rápido (usage)

import os
from imprint import Model

# Cria um modelo simples com uma página e campos dinâmicos
def criar_cracha_basico():
    # caminho do fundo
    caminho_fundo = os.path.join(os.getcwd(), "examples/assets/badge.jpeg")

    # cria modelo
    modelo = Model.new(name="Cracha-Basico")

    # cria página da frente
    pagina_frente = modelo.new_page(name="frente").set_background(caminho_fundo)

    # adiciona campo de texto: nome
    pagina_frente.add_component(name="Nome Completo", component="text", form_key="nome")\
        .set_position((520, 320)).set_size(24)

    # adiciona campo de texto: cargo
    pagina_frente.add_component(name="Cargo", component="text", form_key="cargo")\
        .set_position((510, 400)).set_size(24)

    # adiciona campo de texto: função
    pagina_frente.add_component(name="Função", component="text", form_key="funcao")\
        .set_position((610, 480)).set_size(24)

    # adiciona campo de imagem: foto
    pagina_frente.add_component(name="Foto", component="img", form_key="foto")\
        .set_position((35, 245)).set_dimension((360, 360))

    return modelo

modelo = criar_cracha_basico()

dados_formulario = {
    "nome": "Daniel Fernandes Pereira",
    "cargo": "Desenvolvedor de Software",
    "funcao": "Administrador",
    "foto": os.path.join(os.getcwd(), "examples/assets/photo.png"),
}

# Construir e renderizar
resultado = modelo.build_img(dados_formulario)

# Visualizar no visualizador padrão do sistema
resultado.show()

Observações:

• Model.new(...) cria um novo template.
• Page aceita background por caminho de arquivo; caso não use imagem, especifique width e height.
• form_key associa o componente a uma chave no dicionário form_data passado ao build_...().

🔧 Estrutura da API (resumo)

Model | Modelo

• Model.new(name: str) → Cria uma nova instância de Model com o nome fornecido.
• Model.new_page(name: str) → Cria uma nova Page e a vincula ao Model pai.
• Model.get_form() → Retorna um único dicionário combinando todos os forms de todas as páginas.
• Model.get_schema() → Retorna um dicionário com nomes das páginas como chaves e seus forms como valores.
• Model.export(path: str) → Salva a estrutura do model em um arquivo JSON.
• Model.load(path: str) → Método de classe para carregar um model de um arquivo JSON.

Page | Pagina

• Page.add_component(name: str, component: str, form_key: Optional[str]) → Adiciona um componente (Text ou Img) à página.
• Page.get_component(name: str) → Retorna o componente associado ao nome do campo.
• Page.set_width(width: int) → Define a largura da página.
• Page.set_height(height: int) → Define a altura da página.
• Page.set_dimension(width: int, height: int) → Define largura e altura.
• Page.set_background(background: Union[str, Tuple[int,int,int]]) → Define a imagem ou cor de fundo.

Component | Componente

• Text → Representa componentes de texto. Métodos: get_color(), get_size(), get_position(), get_value(), get_dimension_r(), get_font(), set_color(), set_size(), set_position(), set_value(), set_dimension_r(), set_font()
• Img → Representa componentes de imagem. Métodos: get_position(), get_dimension(), get_path(), set_position(), set_dimension(), set_path(), set_value()

Builder / Renderização

• BuilderMixin.build_img(forms) → Retorna um ImageBuild com as imagens renderizadas.
• Métodos: to_images(), to_image(), to_bytes(page: Optional[int]), save(path: str), show(page: Optional[int])

📌 Boas práticas e dicas

• Use Component com form_key para ligar os campos ao seu dicionário de dados.
• Para imagens, sempre passe caminhos de arquivo válidos ou URIs locais; cuide do tamanho e proporção.
• Ao usar fundo sem imagem, defina width e height na página para evitar erro.

🌟 Contribuições

1. Fork no GitHub.
2. Crie um branch: git checkout -b feature/nome-da-feature.
3. Abra um PR com descrição clara do que foi feito.

📄 Licença

MIT License © Daniel Fernandes

---

English (EN)

Imprint

Imprint is a Python library to programmatically create and generate visual templates (certificates, badges, invitations, etc.) with dynamic fields that can be filled from APIs, spreadsheets, databases or any data source.

⚡ Features

• Create custom templates with multiple pages.
• Dynamic fields: text, image and QR code (more field types planned).
• Define position, size and dimension for each field on a page.
• Export to PNG images; PDF and other export formats are planned.
• Easy integration with APIs, Excel/CSV and databases.
• Modular engine/architecture to allow new render engines and field types.

🚀 Installation

When published on PyPI:

pip install imprintlab

To install from the Git repository (development):

pip install git+https://github.com/danieldevpy/imprint.git

📝 Quickstart example

import os
from imprint import Model

# Build a simple badge template with dynamic fields
def create_basic_badge():
    # Getting background image path
    background_path = os.path.join(os.getcwd(), "examples/assets/badge.jpeg")
    
    # Creating basic model
    model = Model.new(name="Basic-Badge")

    # Creating front page
    front_page = model.new_page(name="front")\
        .set_background(background_path)

    # Adding text field: name
    front_page.add_component(name="Full Name", component="text", form_key="name")\
        .set_position((520, 320))\
        .set_size(24)  # defining component properties

    # Adding text field: job
    front_page.add_component(name="Job", component="text", form_key="job")\
        .set_position((510, 400))\
        .set_size(24)  # defining component properties

    # Adding text field: role
    front_page.add_component(name="Role", component="text", form_key="role")\
        .set_position((610, 480))\
        .set_size(24)  # defining component properties

    # Adding image field: photo
    front_page.add_component(name="Photo", component="img", form_key="photo")\
        .set_position((35, 245))\
        .set_dimension((360, 360))  # defining component properties

    return model

model = create_basic_badge()

form_data = {
    "name": "Daniel Fernandes Pereira",
    "job": "Software Developer",
    "role": "Administrator",
    "photo": os.path.join(os.getcwd(), "examples/assets/photo.png")
}

# Build and render (Pillow engine by default)
result = model.build(form_data).render()

# Build and render
result = model.build_img(form_data)

# Display in the system's default viewer
result.show()

🔧 API Structure (summary)

Model

• Model.new(name: str) → Creates a new Model instance with the given name.
• Model.new_page(name: str) → Creates a new Page and links it to the parent Model.
• Model.get_form() → Returns a single dictionary combining all forms from all pages.
• Model.get_schema() → Returns a dictionary with page names as keys and their forms as values.
• Model.export(path: str) → Saves the model structure to a JSON file.
• Model.load(path: str) → Class method to load a model from a JSON file.

Page

• Page.add_component(name: str, component: str, form_key: Optional[str]) → Adds a component (Text or Img) to the page.
• Page.get_component(name: str) → Returns the component associated with the field name.
• Page.set_width(width: int) → Sets the page width.
• Page.set_height(height: int) → Sets the page height.
• Page.set_dimension(width: int, height: int) → Sets width and height.
• Page.set_background(background: Union[str, Tuple[int,int,int]]) → Sets the background image or color.

Component

• Text → Represents text components. Methods: get_color(), get_size(), get_position(), get_value(), get_dimension_r(), get_font(), set_color(), set_size(), set_position(), set_value(), set_dimension_r(), set_font()
• Img → Represents image components. Methods: get_position(), get_dimension(), get_path(), set_position(), set_dimension(), set_path(), set_value()

Builder / Rendering

• BuilderMixin.build_img(forms) → Returns an ImageBuild with rendered images.
• Methods: to_images(), to_image(), to_bytes(page: Optional[int]), save(path: str), show(page: Optional[int])

📌 Best Practices & Tips

• Use Component with form_key to link fields to your data dictionary.
• For images, always provide valid file paths or local URIs; handle size and proportion carefully.
• When using a background without an image, set width and height on the page to avoid errors.

🌟 Contributions

1. Fork on GitHub.
2. Create a branch: git checkout -b feature/feature-name.
3. Open a PR with a clear description of your changes.

📄 License

MIT License © Daniel Fernandes