baserow.field_config

  1"""
  2This module handles the config/properties of individual Baserow fields. These
  3classes cannot be used to parse/validate data coming from Baserow.
  4"""
  5
  6
  7import abc
  8from datetime import date, datetime, timedelta
  9import enum
 10import random
 11
 12from typing import Annotated, Any, Literal, Optional, Union
 13from pydantic import UUID4, BaseModel, Field, RootModel
 14
 15from baserow.color import BasicColor, Color
 16
 17
 18class FieldConfigBase(BaseModel, abc.ABC):
 19    """
 20    Many of the fields (or rows) in Baserow tables have certain properties that
 21    can be set. These are managed with this class. Each field type implements
 22    its own Config class. Using these config classes, new fields can be created
 23    in a table.
 24    """
 25    name: Optional[str] = Field(max_length=255, default=None)
 26    """Name of the field."""
 27    id: Optional[int] = None
 28    """
 29    Field primary key. Can be used to generate the database column name by
 30    adding field_ prefix.
 31    """
 32    table_id: Optional[int] = None
 33    """Related table id."""
 34    order: Optional[int] = None
 35    """Field order in table. 0 for the first field."""
 36    primary: Optional[bool] = None
 37    """
 38    Indicates if the field is a primary field. If `True` the field cannot be
 39    deleted and the value should represent the whole row.
 40    """
 41    read_only: Optional[bool] = None
 42    """
 43    Indicates whether the field is a read only field. If true, it's not possible
 44    to update the cell value. 
 45    """
 46    relate_fields: Optional[list[dict]] = None
 47    description: Optional[str] = None
 48    """
 49    Optional human readable description for the field. Displayed in Baserow.
 50    """
 51
 52
 53class TextFieldConfig(FieldConfigBase):
 54    """
 55    A single line text field is a type of field that allows you to input short
 56    and unique pieces of text into your table.
 57    """
 58    type: Literal["text"] = "text"
 59    text_default: str = Field(default="", max_length=255)
 60
 61
 62class LongTextFieldConfig(FieldConfigBase):
 63    """
 64    A long text field can contain long paragraphs or multiple lines of text.
 65    """
 66    type: Literal["long_text"] = "long_text"
 67    long_text_enable_rich_text: Optional[bool] = False
 68
 69
 70class URLFieldConfig(FieldConfigBase):
 71    """The URL field holds a single URL."""
 72    type: Literal["url"] = "url"
 73
 74
 75class EMailFieldConfig(FieldConfigBase):
 76    """
 77    An email field is a type of field that allows input of a single email
 78    address in a cell in the right format. When you click on an email address
 79    inside of an email field, your computer's default email client will launch
 80    with the clicked email's To: address in the To: field.
 81    """
 82    type: Literal["email"] = "email"
 83
 84
 85class NumberFieldConfig(FieldConfigBase):
 86    """The number field is a field type that holds numerical values."""
 87    type: Literal["number"] = "number"
 88    number_decimal_places: int = 0
 89    """The amount of digits allowed after the point."""
 90    number_negative: bool = True
 91    """Indicates if negative values are allowed."""
 92
 93
 94class RatingStyle(str, enum.Enum):
 95    """Style of rating symbols."""
 96    STAR = "star"
 97    HEART = "heart"
 98    THUMBS_UP = "thumbs-up"
 99    FLAG = "flag"
100    SMILE = "smile"
101
102
103class RatingFieldConfig(FieldConfigBase):
104    """
105    A rating field is used to rate your rows in order to rank or evaluate their
106    quality.
107    """
108    type: Literal["rating"] = "rating"
109    max_value: int = Field(default=5, ge=1, le=10)
110    """Maximum value the rating can take."""
111    color: BasicColor = Field(default=BasicColor.DARK_BLUE)
112    """Color of the symbols."""
113    style: RatingStyle = RatingStyle.STAR
114    """Style of rating symbols."""
115
116
117class BooleanFieldConfig(FieldConfigBase):
118    """
119    The boolean field represents information in a binary true/false format.
120    """
121    type: Literal["boolean"] = "boolean"
122
123
124class DateFormat(str, enum.Enum):
125    """Format of the date-string."""
126    EU = "EU"
127    """European, D/M/Y, 20/02/2020."""
128    US = "US"
129    """US, M/D/Y, 02/20/2022."""
130    ISO = "ISO"
131    """ISO, Y-M-D, 2020-02-20."""
132
133
134class TimeFormat(int, enum.Enum):
135    """Format of the time. 24 or 23 hour."""
136    HOUR_24 = 24
137    HOUR_12 = 12
138
139
140class GenericDateFieldConfig(FieldConfigBase):
141    """
142    Generic date field config for all field types handling date(-time) values.
143    """
144    date_format: DateFormat = DateFormat.ISO
145    """EU, US or ISO."""
146    date_include_time: bool = False
147    """Indicates if the field also includes a time."""
148    date_time_format: TimeFormat = TimeFormat.HOUR_24
149    """12 (am/pm) or 24 hour format."""
150    date_show_tzinfo: bool = False
151    """Indicates if the timezone should be shown."""
152    date_force_timezone: Optional[str] = Field(default=None, max_length=255)
153    """Force a timezone for the field overriding user profile settings."""
154    date_force_timezone_offset: Optional[int] = Field(default=None)
155    """A UTC offset in minutes to add to all the field datetimes values."""
156
157
158class DateFieldConfig(GenericDateFieldConfig):
159    """
160    A UTC offset in minutes to add to all the field datetimes values.
161    """
162    type: Literal["date"] = "date"
163
164
165class LastModifiedFieldConfig(GenericDateFieldConfig):
166    """
167    The last modified field type returns the most recent date and time that a
168    row was modified. 
169    """
170    type: Literal["last_modified"] = "last_modified"
171
172
173class LastModifiedByFieldConfig(FieldConfigBase):
174    """
175    Track decisions and actions to specific individuals for historical reference
176    or follow-up.
177    """
178    type: Literal["last_modified_by"] = "last_modified_by"
179
180
181class CreatedOnFieldConfig(GenericDateFieldConfig):
182    """
183    The created on field type will automatically show the date and time that a
184    row was created by a user.
185    """
186    type: Literal["created_on"] = "created_on"
187
188
189class CreatedByFieldConfig(FieldConfigBase):
190    """
191    Automatically tracks and displays the name of the collaborator who created
192    each row within a table.
193    """
194    type: Literal["created_by"] = "created_by"
195
196
197class DurationFormat(str, enum.Enum):
198    """Possible display formats for durations."""
199    HOURS_MINUTES = "h:mm"
200    HOURS_MINUTES_SECONDS = "h:mm:ss"
201    HOURS_MINUTES_SECONDS_DECISECONDS = "h:mm:ss.s"
202    HOURS_MINUTES_SECONDS_CENTISECONDS = "h:mm:ss.ss"
203    HOURS_MINUTES_SECONDS_MILLISECONDS = "h:mm:ss.sss"
204    DAYS_HOURS = "d h"
205    DAYS_HOURS_MINUTES = "d h:mm"
206    DAYS_HOURS_MINUTES_SECONDS = "d h:mm:ss"
207
208
209class DurationFieldConfig(FieldConfigBase):
210    """
211    Stores time durations measured in hours, minutes, seconds, or milliseconds.
212    """
213    type: Literal["duration"] = "duration"
214    duration_format: DurationFormat = DurationFormat.HOURS_MINUTES_SECONDS
215    """Possible display formats."""
216
217
218class LinkFieldConfig(FieldConfigBase):
219    """
220    A link to table field creates a link between two existing tables by
221    connecting data across tables with linked rows.
222    """
223    type: Literal["link_row"] = "link_row"
224    link_row_table_id: int
225    """The id of the linked table."""
226    has_related_field: bool = False
227
228
229class FileFieldConfig(FieldConfigBase):
230    """
231    A file field allows you to easily upload one or more files from your device
232    or from a URL.
233    """
234    type: Literal["file"] = "file"
235
236
237class SelectEntryConfig(BaseModel):
238    """Config for a entry in a single or multiple select field."""
239    id: int
240    value: str = Field(max_length=255)
241    color: Color = Field(max_length=255, default=Color.DARK_BLUE)
242
243
244class SingleSelectFieldConfig(FieldConfigBase):
245    """
246    The single select field type is a field type containing defined options to
247    choose only one option from a set of options.
248    """
249    type: Literal["single_select"] = "single_select"
250    select_options: list[SelectEntryConfig]
251
252
253class MultipleSelectFieldConfig(FieldConfigBase):
254    """
255    A multiple select field contains a list of tags to choose multiple options
256    from a set of options. 
257    """
258    type: Literal["multiple_select"] = "multiple_select"
259    select_options: list[SelectEntryConfig]
260
261
262class PhoneNumberFieldConfig(FieldConfigBase):
263    """
264    The phone number field will format a string of numbers as a phone number, in
265    the form (XXX) XXX-XXXX.
266    """
267    type: Literal["phone_number"] = "phone_number"
268
269
270class FormulaType(str, enum.Enum):
271    """Types of formula result value."""
272    INVALID = "invalid"
273    TEXT = "text"
274    CHAR = "char"
275    BUTTON = "button"
276    LINK = "link"
277    DATE_INTERVAL = "date_interval"
278    DURATION = "duration"
279    DATE = "date"
280    BOOLEAN = "boolean"
281    NUMBER = "number"
282    ARRAY = "array"
283    SINGLE_SELECT = "single_select"
284    MULTIPLE_SELECT = "multiple_select"
285    SINGLE_FILE = "single_file"
286
287
288class GenericFormulaFieldConfig(FieldConfigBase):
289    """
290    Generic type for fields which can contain all multiple fields types.
291    """
292    date_show_tzinfo: Optional[bool] = False
293    """Indicates if the timezone should be shown."""
294    number_decimal_places: Optional[int] = 0
295    """The amount of digits allowed after the point."""
296    duration_format: Optional[DurationFormat] = DurationFormat.HOURS_MINUTES_SECONDS
297    """Possible display formats."""
298    date_force_timezone: Optional[str] = Field(default=None, max_length=255)
299    """Force a timezone for the field overriding user profile settings."""
300    array_formula_type: Optional[FormulaType] = None
301    """
302    The type of the values within the array if `formula_type` is set to array.
303    Please note that the type array is not allowed. As an array within an array
304    is not possible in Baserow.
305    """
306    error: Optional[str] = None
307    date_format: Optional[DateFormat] = DateFormat.ISO
308    """EU, US or ISO."""
309    date_include_time: Optional[bool] = False
310    """Indicates if the field also includes a time."""
311    date_time_format: Optional[TimeFormat] = TimeFormat.HOUR_24
312    """12 (am/pm) or 24 hour format."""
313    formula: Optional[str] = None
314    """The actual formula."""
315    formula_type: FormulaType
316    """Type of the formula result."""
317
318
319class FormulaFieldConfig(GenericFormulaFieldConfig):
320    """
321    A value in each row can be calculated using a formula based on values in
322    cells in the same row.
323    """
324    type: Literal["formula"] = "formula"
325
326
327class CountFieldConfig(GenericFormulaFieldConfig):
328    """
329    The count field will automatically count the number of rows linked to a
330    particular row in your database.
331    """
332    type: Literal["count"] = "count"
333
334
335class RollupFieldConfig(GenericFormulaFieldConfig):
336    """Aggregate data and gain valuable insights from linked tables."""
337    type: Literal["rollup"] = "rollup"
338
339
340class LookupFieldConfig(GenericFormulaFieldConfig):
341    """
342    You can look for a specific field in a linked row using a lookup field.
343    """
344    type: Literal["lookup"] = "lookup"
345
346
347class MultipleCollaboratorsFieldConfig(FieldConfigBase):
348    """
349    Assign collaborators by selecting names from a list of workspace members.
350    """
351    type: Literal["multiple_collaborators"] = "multiple_collaborators"
352    notify_user_when_added: bool = False
353
354
355class UUIDFieldConfig(FieldConfigBase):
356    """Create and work with unique record identifiers within a table."""
357    type: Literal["uuid"] = "uuid"
358
359
360class AutonumberFieldConfig(FieldConfigBase):
361    """
362    Automatically generates unique and sequential numbers for each record in a
363    table.
364    """
365    type: Literal["autonumber"] = "autonumber"
366    view: Optional[int] = None
367    """The id of the view to use for the initial ordering."""
368
369
370class PasswordFieldConfig(FieldConfigBase):
371    """
372    Ensure robust security measures for your data. Currently only used for the
373    application builder.
374    """
375    type: Literal["password"] = "password"
376
377
378class AIFieldConfig(FieldConfigBase):
379    """
380    Generate creative briefs, summarize information, and more.
381    """
382    type: Literal["ai"] = "ai"
383    ai_generative_ai_type: Optional[str] = Field(default=None, max_length=32)
384    ai_generative_ai_model: Optional[str] = Field(default=None, max_length=32)
385    ai_prompt: str = ""
386    """The prompt that must run for each row. Must be an formula."""
387
388
389FieldConfigType = Annotated[
390    Union[
391        TextFieldConfig,
392        LongTextFieldConfig,
393        URLFieldConfig,
394        EMailFieldConfig,
395        NumberFieldConfig,
396        RatingFieldConfig,
397        BooleanFieldConfig,
398        DateFieldConfig,
399        LastModifiedFieldConfig,
400        LastModifiedByFieldConfig,
401        CreatedOnFieldConfig,
402        CreatedByFieldConfig,
403        DurationFieldConfig,
404        LinkFieldConfig,
405        FileFieldConfig,
406        SingleSelectFieldConfig,
407        MultipleSelectFieldConfig,
408        PhoneNumberFieldConfig,
409        FormulaFieldConfig,
410        CountFieldConfig,
411        RollupFieldConfig,
412        LookupFieldConfig,
413        MultipleCollaboratorsFieldConfig,
414        UUIDFieldConfig,
415        AutonumberFieldConfig,
416        PasswordFieldConfig,
417        AIFieldConfig,
418    ],
419    Field(discriminator="type"),
420]
421
422
423class FieldConfig(RootModel[FieldConfigType]):
424    root: FieldConfigType
425
426
427class Config:
428    """
429    Encapsulates a FieldConfigType in a non-pydantic model. This is intended to
430    pass the configuration of a field in Baserow to a Table model using
431    typing.Annotated without causing a validation error.
432
433    Args:
434        config (FieldConfigType): An instance of a field config to be
435            encapsulated.
436    """
437
438    def __init__(self, config: FieldConfigType):
439        self.config = config
440
441
442class PrimaryField:
443    """
444    An instance of this class is used to specify, via type annotations, the
445    field of the table that should act as the primary field. Only one field per
446    table can be set as the primary field.
447    """
448
449
450DEFAULT_CONFIG_FOR_BUILT_IN_TYPES: dict[Any, FieldConfigType] = {
451    bool: BooleanFieldConfig(),
452    bytes: TextFieldConfig(),
453    date: DateFieldConfig(),
454    datetime: DateFieldConfig(date_include_time=True),
455    float: NumberFieldConfig(number_decimal_places=3),
456    int: NumberFieldConfig(),
457    str: TextFieldConfig(),
458    timedelta: DurationFieldConfig(),
459    UUID4: UUIDFieldConfig(),
460}
461"""
462Dict mapping each built-in Python type to a Baserow filed config that should be
463used by default for that type. This information is used in the
464Table.create_table() method. For all types that cannot be mapped to a field type
465of a Baserow table, the value is None.
466"""