FastAPI implementation of the libreForms spec
Project description
libreforms-fastapi
FastAPI implementation of the libreForms spec
Getting Started
Follow the steps below to install the system on your computer. Please note, you need to install Python3.10 (or higher) and Python3.10-Venv through your package manager. If you plan to use MongoDB and a relational database, you will need to install these, too. See your distribution's specific instructions for these steps or install using Docker to get started.
cd /opt/libreforms-fastapi
python3 -m venv venv
source venv/bin/activate
pip install libreforms_fastapi
uvicorn libreforms_fastapi.app:app --reload # this will run the development server
You can also install manually using the git repository, which is recommended for development.
git clone https://github.com/signebedi/libreforms-fastapi.git
cd libreforms-fastapi
python3 -m venv venv
source venv/bin/activate
pip install -e .
uvicorn libreforms_fastapi.app:app --reload # this will run the development server
Installing Extras
If you want to also enable the use data science libraries and Excel exports, you should pip install using the data
extras tag.
pip install libreforms_fastapi[data]
If you plan to use Postgres or MariaDB, then there are additional extras tags for those, too.
pip install libreforms_fastapi[postres] # for Postgres
pip install libreforms_fastapi[mariadb] # for MariaDB
Running in Production
To run in production, you need to generate an app configuration and daemonize uvicorn. If this sounds too daunting, consider running the Docker container. If you're not dissuaded, you can use the CLI. After pip installing the package, you can use the libreformsctl
command to get the application running in production. Here's an example:
libreformsctl config production
libreformsctl uvicorn --environment production
libreformsctl nginx production # Optional if you want a reverse proxy
Troubleshooting Errors
You may sometimes run into inexplicable runtime errors. These often result from permission issues on the filesystem. When in doubt, try running the following command as root.
chown -R fastapi:fastapi /opt/libreforms_fastapi
Running in Docker
Follow the instructions below to run in docker. Creating a custom volume is optional but will give you control over the application configurations and, in the event you are using TinyDB and SQLite, you will also be able to access the database files.
git clone https://github.com/signebedi/libreforms-fastapi.git
cd libreforms-fastapi/
sudo docker build -t libreforms-fastapi . # Please note this can take several minutes
sudo docker volume create libreforms-volume # Create a volume for the instance directory
sudo docker run -d --name libreforms-instance -v libreforms-volume:/app/instance -p 8000:8000 libreforms-fastapi
You can create an admin account by running the following commands, being careful to replace <environment>
with the appropriate environment (when in doubt, use development
). Follow the instructions from the interface that pops up.
sudo docker exec -it libreforms-instance libreformsctl useradd --environment <environment> --site-admin
To stop your instance, you can run the following command.
docker kill libreforms-instance
Configuring Your First Form
The form configuration file uses YAML to define the structure and behavior of form fields. Each form is represented as a key under the root, and each field within a form is defined with various parameters specifying its type, label, default values, validation rules, and other attributes. Here’s an example form configuration in YAML:
example_form:
text_input:
input_type: text
output_type: !str
field_label: Text Input
default: Default Text
validators:
min_length: 1
max_length: 200
required: true
description: A text input field
number_input:
input_type: number
output_type: !int
field_label: Number Input
default: 42
validators:
ge: 0
le: 10000
required: false
description: A number input field
checkbox_input:
input_type: checkbox
output_type: !list
field_label: Checkbox Input
options:
- Option1
- Option2
- Option3
required: true
default:
- Option1
- Option3
description: A checkbox input field
another_form:
section_header:
is_header: true
field_label: Section Header
description: This is an example of a section header. You can put as much text here as you need to guide users in the submission of the form in the UI.
select_input:
input_type: select
output_type: !str
field_label: Select a user
options: !all_usernames_by_group_default
required: true
description: A select input field, illustrating how to use data retrieval tags.
Field Parameters
Each field configuration includes several key parameters:
- input_type: Specifies the type of input control to use, such as text, number, email, checkbox, radio, select, etc.
- output_type: Indicates the data type for the field’s output, using custom YAML tags like !str, !int, !list, etc.
- field_label: A user-friendly label for the field, which will be displayed on the form.
- default: The default value to populate the field when the form loads.
- required: A boolean indicating whether the field must be filled out for form submission.
- options: Available choices for fields like select, radio, and checkbox inputs. This can be a static list or dynamically populated using special YAML tags.
- description: A brief description of the field, providing context or instructions for users.
- validators: A set of validation rules for the field, defining constraints like minimum and maximum length, patterns, and numerical limits. These are drawn from pydantic Fields.
Adding Headers
Headers are special fields in the YAML configuration used to group related fields or provide context within the form. Unlike standard fields, headers do not capture user input but serve to organize the form layout and help guide users. Headers support fewer parameters compared to input fields since they primarily focus on labeling and organizing.
- is_header: Indicates that the field is a header. This is typically set to true.
- field_label: The label or title of the header. It acts as a section title or heading in the form.
- description: A brief description or subtitle for the header, providing additional context or information about the section.
Using YAML Tags
The custom loader supports specific YAML tags to define output types and dynamically retrieve data for select, radio, and checkbox fields in forms. These include output_type tags indicating the expected type of a field's output.
- !int: Integer value.
- !str: String value.
- !date: Date value.
- !datetime: Datetime value.
- !time: Time value.
- !timedelta: Time delta value.
- !list: List value.
- !tuple: Tuple value.
- !bytes: Byte value.
These also include data retrieval tags that dynamically yield data for form fields such as select, radio, and checkbox inputs.
- !all_usernames: List of all usernames.
- !all_usernames_by_group_<group_name>: List of usernames for a specific group (replace <group_name> with the actual group name).
- !all_groups: List of all group names.
- !all_submissions_<form_name>: List of form IDs for a specific form type (replace <form_name> with the actual form name).
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for libreforms_fastapi-1.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe3a13a7d3b3bd2c2f84e34b9a6cda4b5292ea67ae5e022fc82307115302fd59 |
|
MD5 | 2fc47a3b277e292949875a60e5a3931c |
|
BLAKE2b-256 | dcd989d8bc0ecb188e62eb12f77fbed7518336832ba161867d010986fa45b8d0 |