codeforms 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

codeforms-0.2.0.dist-info/METADATA

@@ -1,325 +0,0 @@
-Metadata-Version: 2.4
-Name: codeforms
-Version: 0.2.0
-Summary: Python library for creating, validating, and rendering web forms using Pydantic
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.9
-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.9+.
-
-## 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.
-
-## Custom Field Types
-
-You can create your own field types by subclassing `FormFieldBase` and registering them with `register_field_type()`. Custom fields integrate seamlessly with forms, JSON serialization, validation, and HTML export.
-
-### Defining a Custom Field
-
-```python
-from codeforms import FormFieldBase, register_field_type
-
-class PhoneField(FormFieldBase):
-    field_type: str = "phone"       # unique string identifier
-    country_code: str = "+1"
-
-class RatingField(FormFieldBase):
-    field_type: str = "rating"
-    min_rating: int = 1
-    max_rating: int = 5
-
-register_field_type(PhoneField)
-register_field_type(RatingField)
-```
-
-### Using Custom Fields in Forms
-
-```python
-from codeforms import Form, TextField
-
-form = Form(
-    name="feedback",
-    fields=[
-        TextField(name="name", label="Name", required=True),
-        PhoneField(name="phone", label="Phone", country_code="+54"),
-        RatingField(name="score", label="Score", max_rating=10),
-    ],
-)
-```
-
-### JSON Roundtrip
-
-Custom fields serialize and deserialize automatically (as long as the field type is registered before deserialization):
-
-```python
-import json
-
-json_str = form.to_json()
-restored = Form.loads(json_str)
-
-assert isinstance(restored.fields[1], PhoneField)
-assert restored.fields[1].country_code == "+54"
-```
-
-### Listing Registered Types
-
-```python
-from codeforms import get_registered_field_types
-
-for name, classes in sorted(get_registered_field_types().items()):
-    print(f"{name}: {[c.__name__ for c in classes]}")
-```
-
-See [`examples/custom_fields.py`](examples/custom_fields.py) for a full working example.
-
-## License
-
-MIT

codeforms-0.2.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-codeforms/__init__.py,sha256=ckxP8Bn2lku8t6i5UspQNsWsrGw2KAcRyK1mxbgVHoI,1643
-codeforms/export.py,sha256=ygY-bXEerr9bpG0isq1Qesf8F_FtKupgElqQnNcbI0o,15088
-codeforms/fields.py,sha256=e_lGX9XPo1uqTSA490CfGPLwIp8uJzcipv1jqAZNqOo,12819
-codeforms/forms.py,sha256=_wmJ1cDrZCklsx4H12oQ6SlBkDp053Jj7IurpYzudhQ,35766
-codeforms/i18n.py,sha256=p8DPtnvUNMeXXP4YDhvpmIJFQNqOmwK3dEluS6Uch0k,10441
-codeforms/registry.py,sha256=jKpOnvn5fq8x1LkO3va4F-VgruMMXoh-6FUTA-q43p8,6477
-codeforms-0.2.0.dist-info/METADATA,sha256=hUPDRa7k_siVkny9sbU8MT4yMpanRrYyMOVXYg7kUEM,9772
-codeforms-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-codeforms-0.2.0.dist-info/licenses/LICENSE,sha256=U9D6cQ9DZJQrT03MMDJcq-aOuoB_Bn8HJlzcTTN7PfM,1074
-codeforms-0.2.0.dist-info/RECORD,,