codeforms 0.1.0__py3-none-any.whl

codeforms/i18n.py

@@ -0,0 +1,264 @@
+"""
+Internationalization (i18n) module for codeforms.
+
+Provides a configurable message system with locale-based message loading.
+Default locale is English ('en'). Spanish ('es') is also included.
+
+Usage:
+    from codeforms.i18n import set_locale, get_locale, t, register_locale
+
+    # Change locale globally
+    set_locale('es')
+
+    # Get a translated message
+    msg = t('field.required')  # "Este campo es requerido"
+
+    # With interpolation
+    msg = t('field.required_named', name='email')  # "El campo email es requerido"
+
+    # Register a custom locale
+    register_locale('fr', {
+        'field.required': 'Ce champ est obligatoire',
+        ...
+    })
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict, Optional
+
+
+# --- Message catalogs per locale ---
+
+_MESSAGES_EN: Dict[str, str] = {
+    # Field-level validation
+    "field.required": "This field is required",
+    "field.required_named": "The field {name} is required",
+
+    # TextField
+    "text.minlength": "Minimum length is {min}",
+    "text.maxlength": "Maximum length is {max}",
+    "text.pattern_mismatch": "Value does not match the required pattern",
+    "text.invalid_regex": "Invalid regex pattern",
+
+    # EmailField
+    "email.invalid": "Invalid email",
+
+    # NumberField
+    "number.min_value": "Value must be greater than or equal to {min}",
+    "number.max_value": "Value must be less than or equal to {max}",
+    "number.invalid": "Must be a valid number",
+
+    # DateField
+    "date.min_date": "Date must be after {min}",
+    "date.max_date": "Date must be before {max}",
+    "date.invalid_format": "Must be a valid date in YYYY-MM-DD format",
+
+    # SelectField
+    "select.invalid_option": "Invalid option selected",
+    "select.invalid_options": "Invalid options selected",
+    "select.invalid_option_value": "Invalid option: {value}. Must be one of: {valid}",
+    "select.invalid_values": "Invalid values: {values}",
+    "select.min_selected": "Must select at least {min} options",
+    "select.max_selected": "Can select at most {max} options",
+    "select.value_must_be_list": "Value must be a list",
+    "select.min_selected_negative": "min_selected cannot be negative",
+    "select.min_selected_requires_multiple": "min_selected can only be used with multiple=True",
+    "select.max_selected_min_value": "max_selected must be greater than 0",
+    "select.max_selected_requires_multiple": "max_selected can only be used with multiple=True",
+    "select.max_less_than_min": "max_selected must be greater than or equal to min_selected",
+    "select.invalid_value_must_be_one_of": "Invalid value. Must be one of: {valid}",
+
+    # RadioField
+    "radio.invalid_option": "Invalid option selected",
+    "radio.default_must_be_string": "Default value must be a string",
+
+    # CheckboxField
+    "checkbox.must_be_boolean": "Must be a boolean value",
+    "checkbox.default_must_be_boolean": "Default value must be a boolean",
+
+    # CheckboxGroupField
+    "checkbox_group.default_must_be_list": "Default value must be a list of values",
+    "checkbox_group.invalid_options": "Invalid options selected",
+
+    # UrlField
+    "url.invalid_scheme": "URL must start with http:// or https://",
+
+    # Form-level
+    "form.unique_field_names": "Field names must be unique in the form",
+    "form.unique_field_names_in_group": "Field names must be unique within group '{title}'",
+    "form.validation_success": "Data validated successfully",
+    "form.validation_error": "Validation error",
+    "form.data_validation_error": "Data validation error",
+
+    # Export / HTML
+    "export.fix_errors": "Please fix the following errors:",
+    "export.submit": "Submit",
+    "export.field_required": "The field {label} is required",
+}
+
+_MESSAGES_ES: Dict[str, str] = {
+    # Validación a nivel de campo
+    "field.required": "Este campo es requerido",
+    "field.required_named": "El campo {name} es requerido",
+
+    # TextField
+    "text.minlength": "La longitud mínima es {min}",
+    "text.maxlength": "La longitud máxima es {max}",
+    "text.pattern_mismatch": "El valor no coincide con el patrón requerido",
+    "text.invalid_regex": "Patrón regex inválido",
+
+    # EmailField
+    "email.invalid": "Email inválido",
+
+    # NumberField
+    "number.min_value": "El valor debe ser mayor o igual a {min}",
+    "number.max_value": "El valor debe ser menor o igual a {max}",
+    "number.invalid": "Debe ser un número válido",
+
+    # DateField
+    "date.min_date": "La fecha debe ser posterior a {min}",
+    "date.max_date": "La fecha debe ser anterior a {max}",
+    "date.invalid_format": "Debe ser una fecha válida en formato YYYY-MM-DD",
+
+    # SelectField
+    "select.invalid_option": "Opción inválida seleccionada",
+    "select.invalid_options": "Opciones inválidas seleccionadas",
+    "select.invalid_option_value": "Opción inválida: {value}. Debe ser una de: {valid}",
+    "select.invalid_values": "Valores inválidos: {values}",
+    "select.min_selected": "Debe seleccionar al menos {min} opciones",
+    "select.max_selected": "Puede seleccionar máximo {max} opciones",
+    "select.value_must_be_list": "El valor debe ser una lista",
+    "select.min_selected_negative": "min_selected no puede ser negativo",
+    "select.min_selected_requires_multiple": "min_selected solo puede usarse con multiple=True",
+    "select.max_selected_min_value": "max_selected debe ser mayor que 0",
+    "select.max_selected_requires_multiple": "max_selected solo puede usarse con multiple=True",
+    "select.max_less_than_min": "max_selected debe ser mayor o igual que min_selected",
+    "select.invalid_value_must_be_one_of": "Valor inválido. Debe ser uno de: {valid}",
+
+    # RadioField
+    "radio.invalid_option": "Opción inválida seleccionada",
+    "radio.default_must_be_string": "El valor por defecto debe ser una cadena",
+
+    # CheckboxField
+    "checkbox.must_be_boolean": "Debe ser un valor booleano",
+    "checkbox.default_must_be_boolean": "El valor por defecto debe ser un booleano",
+
+    # CheckboxGroupField
+    "checkbox_group.default_must_be_list": "El valor por defecto debe ser una lista de valores",
+    "checkbox_group.invalid_options": "Opciones inválidas seleccionadas",
+
+    # UrlField
+    "url.invalid_scheme": "La URL debe comenzar con http:// o https://",
+
+    # Formulario
+    "form.unique_field_names": "Los nombres de los campos deben ser únicos en el formulario",
+    "form.unique_field_names_in_group": "Los nombres de los campos deben ser únicos dentro del grupo '{title}'",
+    "form.validation_success": "Datos validados correctamente",
+    "form.validation_error": "Error en la validación",
+    "form.data_validation_error": "Error en la validación de datos",
+
+    # Exportación / HTML
+    "export.fix_errors": "Por favor corrija los siguientes errores:",
+    "export.submit": "Enviar",
+    "export.field_required": "El campo {label} es requerido",
+}
+
+
+# --- Registry ---
+
+_locales: Dict[str, Dict[str, str]] = {
+    "en": _MESSAGES_EN,
+    "es": _MESSAGES_ES,
+}
+
+_current_locale: str = "en"
+
+
+# --- Public API ---
+
+
+def get_locale() -> str:
+    """Return the current locale code (e.g. 'en', 'es')."""
+    return _current_locale
+
+
+def set_locale(locale: str) -> None:
+    """
+    Set the current locale.
+
+    Args:
+        locale: A locale code that has been registered (e.g. 'en', 'es').
+
+    Raises:
+        ValueError: If the locale has not been registered.
+    """
+    global _current_locale
+    if locale not in _locales:
+        available = ", ".join(sorted(_locales.keys()))
+        raise ValueError(
+            f"Unknown locale '{locale}'. Available locales: {available}"
+        )
+    _current_locale = locale
+
+
+def get_available_locales() -> list[str]:
+    """Return a sorted list of registered locale codes."""
+    return sorted(_locales.keys())
+
+
+def register_locale(locale: str, messages: Dict[str, str]) -> None:
+    """
+    Register a new locale or update an existing one.
+
+    If the locale already exists, its messages are *merged* (new keys are
+    added, existing keys are overwritten).
+
+    Args:
+        locale: Locale code (e.g. 'fr', 'pt').
+        messages: Dict mapping message keys to translated strings.
+    """
+    if locale in _locales:
+        _locales[locale].update(messages)
+    else:
+        _locales[locale] = dict(messages)
+
+
+def get_messages(locale: Optional[str] = None) -> Dict[str, str]:
+    """
+    Return a *copy* of the message catalog for the given locale.
+
+    Args:
+        locale: Locale code.  Defaults to the current locale.
+    """
+    loc = locale or _current_locale
+    return copy.copy(_locales.get(loc, _locales["en"]))
+
+
+def t(key: str, **kwargs: Any) -> str:
+    """
+    Translate a message key using the current locale.
+
+    Supports Python ``str.format()`` interpolation via keyword arguments.
+
+    Args:
+        key: Message key (e.g. ``'field.required_named'``).
+        **kwargs: Interpolation values (e.g. ``name='email'``).
+
+    Returns:
+        The translated (and optionally interpolated) string.
+        If the key is not found in the current locale, falls back to the
+        English catalog.  If still not found, returns the key itself.
+    """
+    messages = _locales.get(_current_locale, _locales["en"])
+    template = messages.get(key)
+    if template is None:
+        # Fallback to English
+        template = _MESSAGES_EN.get(key, key)
+    if kwargs:
+        try:
+            return template.format(**kwargs)
+        except (KeyError, IndexError):
+            return template
+    return template

codeforms-0.1.0.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: codeforms
+Version: 0.1.0
+Summary: Python library for creating, validating, and rendering web forms using Pydantic
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pydantic[email]>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# codeforms
+
+A Python library for dynamically creating, validating, and rendering web forms using [Pydantic](https://docs.pydantic.dev/).
+
+## Installation
+
+```bash
+pip install codeforms
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add codeforms
+```
+
+Requires Python 3.12+.
+
+## Quick Start
+
+### Creating a Form
+
+Everything starts with the `Form` class. A form is defined with a name and a list of fields.
+
+```python
+from codeforms import Form, TextField, EmailField, NumberField
+
+form = Form(
+    name="UserRegistration",
+    fields=[
+        TextField(name="full_name", label="Full Name", required=True),
+        EmailField(name="email", label="Email", required=True),
+        NumberField(name="age", label="Age"),
+    ]
+)
+```
+
+### The `Form` Class
+
+The `Form` class is the main container for your form structure.
+
+- `id` — Auto-generated UUID.
+- `name` — Form name (used in HTML export and validation).
+- `fields` — A list of field objects (e.g. `TextField`, `EmailField`).
+- `css_classes` — Optional CSS classes for the `<form>` tag.
+- `version` — Form version number.
+- `attributes` — Dictionary of additional HTML attributes for the `<form>` tag.
+
+## Field Types
+
+All fields inherit from `FormFieldBase` and share these common attributes:
+
+- `name` — Field name (maps to `name` in HTML).
+- `label` — User-visible label.
+- `field_type` — Field type (`FieldType` enum).
+- `required` — Whether the field is mandatory.
+- `placeholder` — Placeholder text inside the field.
+- `default_value` — Default value.
+- `help_text` — Help text displayed below the field.
+- `css_classes` — CSS classes for the field element.
+- `readonly` — Whether the field is read-only.
+- `attributes` — Additional HTML attributes for the `<input>` tag.
+
+### Available Fields
+
+- **`TextField`** — Generic text input (`<input type="text">`).
+  - `minlength`, `maxlength`: Min/max text length.
+  - `pattern`: Regex pattern for validation.
+- **`EmailField`** — Email address (`<input type="email">`).
+- **`NumberField`** — Numeric value (`<input type="number">`).
+  - `min_value`, `max_value`: Allowed value range.
+  - `step`: Increment step.
+- **`DateField`** — Date picker (`<input type="date">`).
+  - `min_date`, `max_date`: Allowed date range.
+- **`SelectField`** — Dropdown select (`<select>`).
+  - `options`: List of `SelectOption(value="...", label="...")`.
+  - `multiple`: Enables multi-select.
+  - `min_selected`, `max_selected`: Selection count limits (multi-select only).
+- **`RadioField`** — Radio buttons (`<input type="radio">`).
+  - `options`: List of `SelectOption`.
+  - `inline`: Display options inline.
+- **`CheckboxField`** — Single checkbox (`<input type="checkbox">`).
+- **`CheckboxGroupField`** — Group of checkboxes.
+  - `options`: List of `SelectOption`.
+  - `inline`: Display options inline.
+- **`FileField`** — File upload (`<input type="file">`).
+  - `accept`: Accepted file types (e.g. `"image/*,.pdf"`).
+  - `multiple`: Allow multiple file uploads.
+- **`HiddenField`** — Hidden field (`<input type="hidden">`).
+
+## Data Validation
+
+codeforms offers multiple ways to validate user-submitted data, leveraging Pydantic's validation engine.
+
+### Recommended: `FormDataValidator`
+
+The most robust approach is `FormDataValidator.create_model`, which dynamically generates a Pydantic model from your form definition. This gives you powerful validations and detailed error messages automatically.
+
+```python
+from codeforms import Form, FormDataValidator, TextField, SelectField, SelectOption
+from pydantic import ValidationError
+
+# 1. Define your form
+form = Form(
+    name="MyForm",
+    fields=[
+        TextField(name="name", label="Name", required=True),
+        SelectField(
+            name="country",
+            label="Country",
+            options=[
+                SelectOption(value="us", label="United States"),
+                SelectOption(value="uk", label="United Kingdom"),
+            ]
+        )
+    ]
+)
+
+# 2. Create the validation model
+ValidationModel = FormDataValidator.create_model(form)
+
+# 3. Validate incoming data
+user_data = {"name": "John", "country": "us"}
+
+try:
+    validated = ValidationModel.model_validate(user_data)
+    print("Valid!", validated)
+except ValidationError as e:
+    print("Validation errors:", e.errors())
+```
+
+This approach integrates seamlessly with API backends like FastAPI or Flask, since it produces standard Pydantic models.
+
+### Other Validation Methods
+
+Two simpler alternatives exist, though `FormDataValidator` is preferred:
+
+1. `form.validate_data(data)` — Built-in method on the `Form` class. Less flexible; doesn't produce Pydantic models.
+2. `validate_form_data(form, data)` — Standalone function with basic validation logic.
+
+## Exporting Forms
+
+Once your form is defined, you can export it to different formats.
+
+```python
+# Export to plain HTML
+html_output = form.export('html', submit=True)
+print(html_output['output'])
+
+# Export to HTML with Bootstrap 5 classes
+bootstrap_output = form.export('html_bootstrap5', submit=True)
+print(bootstrap_output['output'])
+
+# Export to JSON
+json_output = form.to_json()
+print(json_output)
+
+# Export to a Python dictionary
+dict_output = form.to_dict()
+print(dict_output)
+```
+
+### Supported Formats
+
+| Format | Description |
+|---|---|
+| `html` | Semantic HTML |
+| `html_bootstrap4` | HTML with Bootstrap 4 classes |
+| `html_bootstrap5` | HTML with Bootstrap 5 classes |
+| `json` | JSON representation of the form |
+| `dict` | Python dictionary representation |
+
+HTML export can also generate a `<script>` block for basic client-side validation.
+
+## Internationalization (i18n)
+
+All validation and export messages are locale-aware. **English** (`en`) and **Spanish** (`es`) are included out of the box, and you can register any additional language at runtime via `register_locale()`.
+
+### Switching Locales
+
+```python
+from codeforms import set_locale, get_locale, get_available_locales
+
+print(get_locale())            # "en"
+print(get_available_locales()) # ["en", "es"]
+
+set_locale("es")
+# All validation messages will now be in Spanish
+```
+
+### Registering a Custom Locale
+
+You can add any locale at runtime. Missing keys automatically fall back to English.
+
+```python
+from codeforms import register_locale, set_locale
+
+register_locale("pt", {
+    "field.required": "Este campo é obrigatório",
+    "field.required_named": "O campo {name} é obrigatório",
+    "email.invalid": "E-mail inválido",
+    "number.min_value": "O valor deve ser maior ou igual a {min}",
+    "form.validation_success": "Dados validados com sucesso",
+    "form.data_validation_error": "Erro na validação dos dados",
+})
+
+set_locale("pt")
+```
+
+### Using the Translation Function
+
+The `t()` function translates a message key, with optional interpolation:
+
+```python
+from codeforms import t, set_locale
+
+set_locale("en")
+print(t("field.required"))                     # "This field is required"
+print(t("field.required_named", name="email")) # "The field email is required"
+
+set_locale("es")
+print(t("field.required"))                     # "Este campo es requerido"
+print(t("text.minlength", min=3))              # "La longitud mínima es 3"
+```
+
+### Locale-Aware Validation
+
+All validation functions respect the active locale:
+
+```python
+from codeforms import Form, TextField, validate_form_data, set_locale
+
+form = Form(
+    name="example",
+    fields=[TextField(name="name", label="Name", required=True)]
+)
+
+set_locale("en")
+result = validate_form_data(form, {})
+print(result["errors"][0]["message"])  # "The field name is required"
+
+set_locale("es")
+result = validate_form_data(form, {})
+print(result["errors"][0]["message"])  # "El campo name es requerido"
+```
+
+See [`examples/i18n_usage.py`](examples/i18n_usage.py) for a full working example.
+
+## License
+
+MIT

codeforms-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+codeforms/__init__.py,sha256=sk4cFfqYAd5LzAgkL35Wm-0uHtYAksMICX6ak5Y0DI8,590
+codeforms/export.py,sha256=CCJJm6XxoUoPh88PGJBiO7KePD8tXvhq2mqJWSuy-_c,12472
+codeforms/fields.py,sha256=gijcydSB4dbABN76cUxpi8KhtUnTrW15YGzDVYjqduE,9343
+codeforms/forms.py,sha256=lzsKXQdbun-gc7y6D5DjjNf2OxMFnUd4H_0JsPW8KA0,23383
+codeforms/i18n.py,sha256=_wuPwelKgLFac_vW9AeYa-MR2AAoLIlNbNTXV80CYwM,9510
+codeforms-0.1.0.dist-info/METADATA,sha256=Q2cYBCMbe7ack6GcKx2HAxNkKFFJWzfZrr6ysjKTdKY,8158
+codeforms-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+codeforms-0.1.0.dist-info/licenses/LICENSE,sha256=U9D6cQ9DZJQrT03MMDJcq-aOuoB_Bn8HJlzcTTN7PfM,1074
+codeforms-0.1.0.dist-info/RECORD,,

codeforms-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codeforms-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Pablo Manson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.